MCP Integration

Let an AI coding assistant act on your Velocis workspace through the Model Context Protocol.

Talk to Velocis in natural language

The Velocis MCP server lets an AI editor (Claude Desktop, Cursor, Antigravity, and others) call 60 Velocis tools on your behalf. Permission is re-checked on the server against your own project membership, so a tool can never see more than you can.

Register a login-bug issue in the VEL project
Move VEL-101 to in_progress and assign it to me
Summarize my work this week, grouped by issue

Getting started

Issue a personal access token from Profile → Integrations → Access tokens, then set it as VELOCIS_ACCESS_TOKEN in your MCP client environment (see the environment variables below).

Environment variables

Variable	Description	Default
`VELOCIS_ACCESS_TOKEN`Required	Personal access token. Required — without it the server fails immediately, with no network round-trip.	`—`
`VELOCIS_BASE_URL`	Backend base URL.	`http://localhost:3001`
`VELOCIS_TIMEOUT_MS`	Request timeout, in milliseconds.	`30000`
`VELOCIS_UPLOAD_TIMEOUT_MS`	Attachment upload timeout (longer than the default), in milliseconds.	`120000`
`VELOCIS_MIN_BACKEND_VERSION`	Minimum backend release this build requires.	`—`
`VELOCIS_SKIP_BACKEND_VERSION_CHECK`	Disable the version-compatibility check.	`false`

Things to know first

Each tool's schema documents this in full — here are the parts that surprise people.

What a query returns

Listing issues with no status filter includes done and cancelled ones — narrow it by excluding those statuses explicitly. Getting a single issue returns it regardless of status.

A filter can silently widen

A search token nobody recognized is dropped rather than applied, which widens the result. That token comes back in the response so it can be fixed and retried, rather than reporting a filter that never took effect.

Clearing a field is not the same as omitting it

To clear an assignee, due date, or parent on update, pass an explicit empty value. Omitting the field leaves it unchanged.

Tag issues at creation time

A workflow trigger gated on a tag only fires if the tag is present when the issue is created — attaching it afterward cannot retroactively fire an event that already happened.

Do not hand-compute an allocation split

Pass the per-day distribution a recommendation tool returns straight through — collapsing it to a single average number loses the daily distribution, and the server rejects anything that exceeds capacity.

What cannot be undone

Deleting a page or an attachment, and any bulk delete, is permanent and requires an explicit confirmation flag.

Errors

A failed call returns an error code, the cause, and what to try next, all as text — MCP responses are plain text and cannot carry a structured object.

HTTP status	Code	Meaning
400	`VALIDATION_ERROR`	The request body was rejected — the message names the field.
401	`UNAUTHORIZED`	The token is missing, expired, or revoked.
403	`PERMISSION_DENIED`	Your role does not allow this.
404	`NOT_FOUND`	Not found — or you cannot see it, which reads the same.
409	`CONFLICT`	The underlying record changed since you read it — re-read and retry.
429	`RATE_LIMIT_EXCEEDED`	Too many requests.
5xx	`INTERNAL_ERROR`	Retrying the same request will not fix it.

Available tools

velocis_add_comment

Add a comment to an issue.

velocis_add_issues_to_sprint

Add one or more issues to a sprint.

velocis_add_tag

Attach a tag to an issue.

velocis_advanced_search

Search issues with a multi-condition, JQL-style query string.

velocis_allocate

Book a user's time on an issue across a date range.

velocis_attach_file

Upload local files as attachments on an issue.

velocis_bulk_action

Apply one action to many issues at once.

velocis_complete_sprint

Close a sprint and decide what happens to its unfinished issues.

velocis_create_issue

Create an issue in a project.

velocis_create_milestone

Create a milestone in a project: a wave of an epic or a checkpoint of an initiative.

velocis_create_page

Create a documentation page, with an optional Markdown body.

velocis_create_sprint

Create a sprint in a project.

velocis_delete_attachment

Delete one attachment from an issue.

velocis_delete_milestone

Delete a project's milestone (wave or checkpoint).

velocis_delete_page

Delete a documentation page.

velocis_export_issue_doc

Write an issue's Doc tab to a local Markdown file and return its path.

velocis_find_best_assignee

Rank a project's members for an issue by how well each fits the work, accounting for their remaining capacity.

velocis_find_similar_issues

Find existing issues that look like a draft title — check before filing or starting work.

velocis_get_comments

Read an issue's comment thread, oldest first.

velocis_get_custom_fields

List a project's custom field definitions.

velocis_get_goal

Get one goal with its progress, key results and linked issues.

velocis_get_goals

List the goals you can see, optionally narrowed to specific projects.

velocis_get_issue

Get a single issue by its number or id.

velocis_get_issue_allocations

List who is booked on an issue, and for how many hours per day.

velocis_get_issue_doc

Read an issue's Doc tab as Markdown.

velocis_get_issue_history

Read an issue's full change history: field edits, status transitions, assignee changes and comments.

velocis_get_issue_transitions

Get an issue's current status and the statuses it may move to next.

velocis_get_issues

List issues, with optional filters.

velocis_get_page

Get a documentation page by its slug or id.

velocis_get_project_calendar

Get a project's per-user allocation calendar over a date range.

velocis_get_projects

List the projects you are a member of.

velocis_get_sprint

Get one sprint and its issues, by id, by name, or as the project's current sprint.

velocis_get_sprints

List a project's sprints.

velocis_get_user_work_summary

Summarise one user's work over a date range, grouped by issue.

velocis_get_user_workload

Get a user's allocated, actual and capacity hours per day over a date range.

velocis_get_workflow_meta

Get the workflow rule builder's schema: condition fields, operators and action types.

velocis_get_workspace_calendar

Get the allocation calendar across every project and user.

velocis_link_issues

Link two issues, for example as blocking or related.

velocis_list_milestones

List a project's milestones (waves) with their progress.

velocis_move_allocation

Move an allocation to a different user or date.

velocis_recommend_allocation

Suggest how to spread a total number of hours across days for one user, respecting capacity, weekends and holidays.

velocis_record_qa_result

Record a QA verdict, with an optional structured report, on a test issue.

velocis_remove_allocation

Delete one or more allocations.

velocis_remove_issue_from_sprint

Remove an issue from a sprint.

velocis_remove_tag

Detach a tag from an issue.

velocis_reorder_sibling

Move an issue before or after a sibling in its parent's order.

velocis_replan_allocation

Replace an issue's allocations with a new distribution, in one transaction.

velocis_search_pages

Search documentation pages by keyword, across both titles and page bodies.

velocis_set_issue_favorite

Add an issue to, or remove it from, the caller's own favorites.

velocis_sheets_list_links

List a project's Google Sheets links.

velocis_simulate_allocation

Check whether a set of per-day hours fits a user's remaining capacity, without writing anything.

velocis_unlink_issues

Remove a link between two issues.

velocis_update_issue

Update an issue's fields, such as its assignee, priority, title or due date.

velocis_update_issue_doc

Write an issue's Doc tab from Markdown.

velocis_update_key_result

Update one key result under a goal, for example to log its current value.

velocis_update_milestone

Update, close, reopen or reorder a project's milestone (wave).

velocis_update_page

Update a documentation page's metadata, its Markdown body, or both.

velocis_update_sprint

Update a sprint's name, goal, dates or state.

velocis_update_status

Change an issue's status.

velocis_whoami

Report which credential the server is using and what it can reach — start here when a call is rejected.