MCP Tools Reference
MCP requires a Pro, Business or Enterprise workspace. Follow the setup guide for OAuth or a connection token. Use tools/list on your connected server for its current tool schemas; listing a tool does not bypass its scope, role, feature or worker requirements. Tool failures can return isError: true inside an HTTP 200 JSON-RPC result, so check the result before treating an action as complete.
Local workers publish bounded operational progress with append_agent_run_events. This host-only tool requires the current run and execution lease headers; it accepts ordered fixed event codes and timestamps, with optional bounded, redacted command diagnostics, and for failed tool calls the tool name, one bounded reason line and a permission marker. Arbitrary SDK payloads, tool arguments and tool results are not accepted.
Parameters and access requirements for Velocity’s 91 MCP tools.
Saved delivery profiles
get_agent_delivery_profile takes profileId: claudeCode, codex, anthropic, grok, muse, cursor or antigravity. It returns shared defaults/limits, your own preferences, revisions, capabilities and recent shared/caller-owned audit history. shared.defaults.maxRepairAttempts is the shared automatic repair default (unset means 0) and shared.limits.maxRepairAttempts the protected maximum (unset means 3). Claude API (anthropic) does not support native Git delivery, so its settings can be read but not saved.
update_agent_delivery_profile takes profileId, scope (workspace or personal), expectedRevision, expectedSharedRevision and settings. Owners/admins edit shared defaults/limits; members edit only their own permitted preferences. Personal settings accept mode, validationRequired, deploymentRequired and requiredChecks. Shared settings contain defaults (the same fields plus an optional maxRepairAttempts) and limits (maxMode, the three requirement fields and an optional maxRepairAttempts). Repair values are whole numbers from 0 to 3, and the default cannot exceed the maximum. Personal preferences cannot set repair work. Empty preferences inherit; no commands, credentials or user selector are accepted. Both revisions must match. Managed executions cannot edit profiles. Host profilePreferences opt-in enables saved defaults; protected limits and explicit CLI limits always apply. Approving extra repairs for a stopped run is browser-only and not available through MCP. Edits require a new attempt before more delivery writes.
Planning pipeline
run_planning_pipeline
Requires current workspace editing access, AI feature access and available credits, plus mcp:read and mcp:write. Enable the cloud agent before starting. Supply teamId and either a description for the PRD stage or prdId for later stages. Optional fields are projectId, startStage, stopStage, maxCostCents and checkpointMode. Stages are prd, stories, split and issues.
The default each_stage mode asks for PRD, refined-story and issue approvals in the browser. at_end requires a Business or Enterprise administrator to enable it. An omitted cap inherits the workspace default (initially 500 cents); zero prevents paid work. Every paid attempt reserves against that cap. The tool returns a run ID; open the run in Agents to inspect usage, review proposals and navigate to created artifacts. MCP clients and agent workers cannot approve checkpoints.
Agent issue lifecycle
report_agent_outcome
Managed issue workers supply issueId and outcome:done for verified complete work, needs_input for a question to the original user,in_progress for remaining work, blocked or clarification when help is needed,no_changes when no changes result, or cancelled with acancellationCommentId pointing to that user’s confirmation on the issue.
A native worker whose implementation is complete but whose required checks cannot run in its sandbox reports ready_for_validation. The server accepts it only while the run’s host workflow requires validation; the host then runs its own pinned checks. It is not tested or delivered work and never closes the issue. Without such a workflow, report in_progress.
When the remaining change edits files that exist only on a different open pull request in the issue’s repository, add dependency (pullRequestUrl, the inspectedheadSha, 1–20 paths and the requiredChange) within_progress. The server re-reads the PR from GitHub, rejects merged, closed, fork or moved heads and any path the PR does not add or change, then keeps one integration task per issue and PR. Its response routes the work: an owner or admin can claim a separate integration in a fresh worktree pinned to that head, or the response names the one missing grant (report blocked and state it once). While the dependency is open, done, ready_for_validation,no_changes, needs_input and clarification are refused, so partial or detector-only work cannot close the issue. The recovery queue shows the task; claiming re-reads the PR head, repository mapping, push access, stop policy and active work, and starts no coding run. The issue completes only from a verified continuation linked to the original attempt.
The server applies workspace/provider settings at claim (assignment and In Progress by default). A reported outcome takes effect only when the runner completes successfully. Feedback returns ownership to the requesting user in Needs Feedback or Blocked; missing outcomes leave work open. Human reassignment or status changes after the claim take precedence. The runner posts the final response according to the configured comment behavior, using the agent’s identity. Intermediate comments should add meaningful decisions or context. Triage and review runs do not own the issue lifecycle. Ordinary MCP clients manage assignment and statuses with issue tools.
Owners/admins configure lifecycle defaults and sparse Claude/Codex overrides with the GraphQLagentIssueWorkflowSettings and updateAgentIssueWorkflowSettings operations. Each poll returns current effective settings; the server rechecks settings at each lifecycle action. Assignment, statuses, comments and feedback handoffs can be configured independently. By default, completion requires confirmed push, merge, deployment and acceptance evidence from the host. Protected delivery requirements always apply. Missing configured statuses fail without choosing an unrelated status; errors, interruptions and no-change work stay open.
Shared agent controls
Settings → Agents → Loops lets paid workspace owners/admins control which issues existing workers can claim, the shared concurrency cap, provider/execution preference and emergency stop. These controls do not start workers or schedule issues. Provider models, repository mappings, worktrees and delivery authorization retain their existing behavior.
get_agent_loop_settings
No arguments. Requires mcp:read and current paid workspace membership. Returns workspaceId, revision, draftRevision,publishedDraftRevision, enabled, settings,controlScope: claims and the eight supported enforcedFields. Reads do not create or enable controls. Model/effort, budgets, priority ordering, worktree and delivery overrides are not supported by this contract.
update_agent_loop_settings
Requires mcp:write and current owner/admin permissions. Supply both revisions from a fresh read. For action: apply, supply all eight settings fields; saving and activation happen atomically. A failed activation changes no draft, active controls or events. Foraction: disable, omit settings. Unsupported fields are rejected. Managed executions cannot modify their own shared limits.
{
"action": "apply",
"expectedRevision": 0,
"expectedDraftRevision": 0,
"settings": {
"teamIds": [], "projectIds": [], "statusIds": [],
"selection": "todo", "concurrency": 1,
"providerPreference": "configured", "executionPreference": "configured",
"emergencyStop": false
}
}Empty team/project lists include all workspace teams/projects. Use selected_statuseswith nonempty status IDs to choose admission statuses. Blocked/review/waiting/terminal work cannot enter; previously admitted work can move to In Progress. Unavailable provider/executor combinations are rejected. Existing stricter provider caps still apply.
Applying controls cancels incompatible/excess runs and outstanding approvals. Emergency stop cancels queued/active work and prevents claims, managed actions and lease renewals. Disabling or resuming does not requeue cancelled work. On CONFLICT, reread and review current settings before resubmitting; do not blindly retry a stale edit. Accepted changes use redacted agent_loop_policy_drafts journal events. Tokens, provider credentials and repository paths are excluded.
The management CLI supports velocity agents loop-settings andvelocity agents update-loop-settings --input @controls.json. MCP calls are also available through velocity api mcp get_agent_loop_settingswith an MCP-scoped token.
Agent repository selection
get_issue_workflow
Reads the issue's saved workflow overrides, interpreted user cue, recent worker capability preview and most recent pinned attempt, including the revision and value sources. Requires issueId. This read does not authorize delivery.
create_issue and update_issue acceptagentWorkflowOverrides: optional mode(local, pr, merge or deploy), validationRequired,deploymentRequired and requiredChecks (existing host check names). Use null or an empty object to clear overrides and cues. Merge/deploy require an owner or admin; managed agents cannot edit their own execution settings. Commands and credentials are never accepted here.
get_agent_repository
Read and verify the current workspace GitHub repository for an issue or team/project. Supply issueId (UUID or identifier), or team (UUID or identifier) with optional projectId. An issue determines its own project. Project mappings take precedence over team mappings; missing or ambiguous mappings require selection in GitHub settings.
Returns workspace/team/project/issue IDs, repository, baseBranch, baseCommit,canPush and the configured branchName for an issue (null during setup). It reads current GitHub repository access and branch state without creating a branch or returning credentials. Native workers use this during local repository linking and recheck mappings before claim and delivery.
Monitor an issue and wait for checks
monitor_issue
Supply issueId, optional cursor, limit (1–100, default 50) and waitSeconds (0–20, default 0). Returns issue edits and metadata notifications, comments, linked integration callbacks and agent run updates for that issue only. Each event identifies the issue and change; callbacks include current PR/check or agent status without provider logs or secrets.
Process events, deduplicate by ID and save nextCursor. Repeat with that cursor to resume. Drain hasMore even on empty pages. On snapshotRequired, retain the new cursor, read get_issue_context, then resume. History covers seven days. Callback snapshots can be newer than their notification; reread context before acting. Deleted callback rows are omitted.
wait_for_issue_checks
Supply issueId, repository, PR number, exact headSha,branch, baseBranch and optional waitSeconds (0–20, default 20). The PR must already be linked to this issue and match its configured repository. Waits for all currently reported GitHub check runs and commit statuses on that head. completed includes failed checks; inspect state and reason. No checks remains pending. A changed head or incomplete provider response is an error. Reviews and merge rules retain their separate delivery checks.
Both tools require mcp:read. Managed workers can monitor only their source issue. The tool response resumes the current agent turn; after timedOut, repeat the call. No background agent is started or durable model suspension created. Existing integration policies and delivery controls keep lifecycle authority; deferred automations can produce later notifications.
Workspace events
list_workspace_events
Read committed changes from the same journal that updates the web UI. Events contain identifiers, changed field names and recorded actor provenance; descriptions, comment bodies, provider secrets and agent prompts/output are excluded. Unattributed service writes are marked unknown.
| Parameter | Type | Required | Description |
|---|---|---|---|
cursor | string | No | Previous nextCursor; omit for retained history |
limit | number | No | 1–100 events, default 50 |
sources | string[] | No | Optional table sources, such as issues, comments, issue_activities or claude_agent_runs |
velocity api mcp list_workspace_events --args '{"limit":50,"sources":["issues","comments","claude_agent_runs"]}'Persist nextCursor after processing each page; follow hasMore and deduplicate by event ID. Cursors belong to the workspace, user and source filter. When snapshotRequired is true, retain the returned cursor, read fresh entity state, and resume from that cursor. Changing filters also requires a fresh snapshot. Replay covers seven days; expired data is excluded even before bounded daily cleanup runs.
For live delivery, use GET /api/workspace-events/feed with the same MCP bearer credential and optional cursor, limit and comma-separated sources query parameters. Browser/native session clients supply workspaceId. Credentials belong in authorization headers or session cookies, never URLs. SSE checkpoints carry id; reconnect with Last-Event-ID. An expired initial cursor returns HTTP 410 with a fresh snapshot cursor; expiry during a connection emitssnapshot_required. Revoked access closes the feed without further content.
Connections renew after 270 seconds, recheck authorization at least every 15 seconds and before each page, and queue at most one bounded page for slow readers. Connection attempts are limited to 30 per verified user per minute in each server instance. Apply client reconnect backoff, and fall back to the paginated MCP tool when streaming is unavailable. This endpoint is separate from MCP transport and protocol negotiation.
Issue Tracking
list_issues
List issues in the workspace with optional filters.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | No | Filter by project ID |
statusId | string | No | Filter by status ID |
priority | string | No | Filter by priority: URGENT, HIGH, MEDIUM, LOW, NONE |
assigneeId | string | No | Filter by assignee user ID |
labelId | string | No | Filter by label ID |
limit | number | No | Max results (default 50, max 50) |
offset | number | No | Offset for pagination |
get_issue
Get issue details including labels, parentId, a structured parent (or null), and a page of direct children. Each related issue includes its ID, identifier, title, team, status and parent ID. Relationships use persisted issue data.
| Parameter | Type | Required | Description |
|---|---|---|---|
issueId | string | Yes | Issue UUID or identifier (e.g., "ENG-123") |
childrenLimit | integer | No | Direct children per page, 1–50; default 50 |
childrenOffset | integer | No | Offset, default 0. Continue while childrenPage.hasMore is true; childrenPage.totalCount is the total direct-child count. |
create_issue
Create a new issue in the workspace. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Issue title |
description | string | No | Issue description (plain text, Markdown, or HTML). Markdown is automatically rendered as rich text in the UI. |
teamId | string | Yes | Team ID to create the issue in |
projectId | string | No | Project ID to assign to |
priority | string | No | Priority: URGENT, HIGH, MEDIUM, LOW, NONE |
statusId | string | No | Status ID (defaults to team's default status) |
assigneeId | string | No | User ID to assign |
parentId | string | No | Parent issue UUID or identifier |
userStoryId | string | No | Story UUID or US identifier in this workspace |
labelIds | string[] | No | Label IDs to attach |
update_issue
Update an existing issue. Only provided fields are changed. Requires mcp:write scope.
Set parentId to a parent issue UUID or identifier in this workspace, replace it to reparent, or send null to clear the parent. Existing issue content stays unchanged when only this relationship is edited. Self-links, cycles and foreign-workspace parents are rejected with a clear error. The same parent/child relationship appears in the issue detail panel.
| Parameter | Type | Required | Description |
|---|---|---|---|
issueId | string | Yes | Issue UUID to update |
title | string | No | New title |
description | string | No | New description (plain text, Markdown, or HTML). Markdown is automatically rendered as rich text in the UI. |
priority | string | No | New priority |
statusId | string | No | New status ID |
assigneeId | string | No | New assignee (null to unassign) |
search_issues
Full-text search across issue titles, descriptions, and identifiers.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search query string |
limit | number | No | Max results (default 20, max 50) |
add_comment
Add a comment to an issue. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
issueId | string | Yes | Issue UUID to comment on |
body | string | Yes | Comment text (plain text or markdown) |
parentId | string | No | Parent comment ID for threaded replies |
list_comments
List all comments on an issue, ordered by creation date.
| Parameter | Type | Required | Description |
|---|---|---|---|
issueId | string | Yes | Issue UUID |
PRDs, requirements and user stories
These 19 tools share the same implementation with Velocity’s cloud agent. Every reference stays in the connected workspace. PRDs and stories accept UUIDs or PRD-3/US-12; requirements accept UUIDs or R2 within a specified PRD. List pages use limit (1–50) and offset, and return nodes and totalCount.
| Tool | Arguments | Behavior |
|---|---|---|
list_prds | status[], projectId, teamId, limit, offset | Filter and page PRDs. |
get_prd | prdId | Body, requirements, coverage and progress. |
list_user_stories | prdId, status[], teamId, projectId, limit, offset | Filter and page stories. |
get_user_story | storyId | Story, acceptance criteria, requirements and issue progress. |
create_prd | input | Create a draft; accepts the proposed draft unchanged, including requirements. |
update_prd | prdId, input, expectedUpdatedAt? | Edit title, summary, content or owner; content edits reopen approved PRDs for review. |
set_prd_status | prdId, status | DRAFT, IN_REVIEW or ARCHIVED. Human approval stays in Velocity. |
create_prd_requirement | prdId, input | Add a titled requirement; optional description, type and priority. |
update_prd_requirement | prdId, requirementId, input | Edit a requirement by UUID or R key. |
create_user_story | input, prdId? | Accept a proposal unchanged; resolve requirementKeys within its PRD. |
update_user_story | storyId, input | Edit story fields and optionally replace requirementIds or requirementKeys. |
split_user_story | storyId, pattern, children[] | Apply a reviewed split; keep pattern and child proposals unchanged. |
create_issues_from_stories | items[] | Add storyId and teamId to each reviewed issue proposal. Reuses ordinary creation, events, embeddings and triage. |
link_issue_to_story | issueId, storyId | Link existing work to its story. |
propose_prd | description, step?, answers?, feedback?, projectIds?, teamIds? | Clarify or draft (default); returns proposals only. |
propose_stories | prdId, requirementKeys?, step? | Estimate or generate (default); INVEST, duplicate flags and coverage. |
check_story | storyId | INVEST assessment and proposed edits. |
propose_story_split | storyId, pattern? | Proposed children and verified criterion mapping. |
propose_issues_for_story | storyId, step? | Estimate or generate (default); implementation proposals and criterion gaps. |
The four read tools require mcp:read. Every mutation and AI proposal also requires mcp:write. AI proposals use the same plan entitlement, credits, model routing and usage accounting as the web app, attributed to the acting user with source agent. Exhausted credits return AI_BUDGET_EXCEEDED. Proposals create no PRDs, stories or issues; review their content and apply the selected items separately.
propose_prd({ description: "Make checkout work offline", step: "draft" })
// Review result.draft, then apply it unchanged:
create_prd({ input: result.draft })
propose_stories({ prdId: "PRD-3", requirementKeys: ["R2"] })
// Review one result.proposals item, then:
create_user_story({ prdId: "PRD-3", input: result.proposals[0] })
propose_story_split({ storyId: "US-12", pattern: "WORKFLOW_STEPS" })
// Review result.children and criterion coverage, then:
split_user_story({ storyId: "US-12", pattern: result.pattern, children: result.children })Unrestricted manual managed runs can use planning tools. Triage, review and restricted automation can read planning context; planning writes require a compatible manual run. Emergency stop and run revocation remain enforced.
Issue attachments
Private screenshots and files use the existing issue storage lifecycle. get_issue and get_issue_context include ready attachment metadata. See the complete API and client workflow for authenticated transfers, limits, CLI examples and retries.
| Tool | Arguments | Result |
|---|---|---|
prepare_issue_attachment | Required: issueId, uploadId (UUID), name, contentType | Resolved issue/upload IDs and credential-free binary API instructions; preparation alone uploads nothing. Requires mcp:write. |
upload_issue_attachment | Required: issueId, uploadId (UUID), name, contentType, data (canonical padded base64) | Actual ready attachment metadata, up to 1 MiB decoded. Larger files use preparation and the 4 MiB binary API. Requires mcp:write. |
list_issue_attachments | Required: issueId | Up to 50 ready files ordered by creation time and ID. |
get_issue_attachment | Required: attachmentId (UUID). Optional: includeImage (false by default) | Private metadata and optionally a validated small image content block. Larger images/files use the authenticated API URL. |
remove_issue_attachment | Required: issueId, attachmentId (UUID) | Removes an ordinary file; embedded description images use the browser or version-checked CLI. Requires mcp:write. |
issueId accepts a UUID or workspace identifier. contentType is image/png, image/jpeg, image/webp or application/octet-stream. Retain a client-generated uploadId for each file and explicitly retry the same bytes/name/type/ID. Never recreate an issue after an upload failure. A remote server cannot read your local path or automatically access an image in a conversation; clients without byte transfer use CLI upload or browser paste/file controls.
Projects & Cycles
list_projects
List all projects in the workspace with optional status filter.
| Parameter | Type | Required | Description |
|---|---|---|---|
status | string | No | Filter by status: BACKLOG, PLANNED, IN_PROGRESS, PAUSED, COMPLETED, CANCELLED |
get_project
Get detailed information about a project including milestones and issue count.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Project UUID |
create_project
Create a project in the connected workspace. Requires mcp:write. As in the app, any current member of the workspace may create projects. The workspace is always the connection's: there is no workspaceId parameter, and unknown parameters are rejected. Validation errors name the field; a duplicate identifier or a leadId who is not a member of the workspace is refused. Webhook subscribers receive project.created.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | 1–255 characters |
identifier | string | Yes | 1–10 letters and digits, starting with a letter, unique in the workspace (for example WEB or API2). Lowercase is uppercased. |
description | string | No | Plain text, up to 10,000 characters |
status | string | No | BACKLOG (default), PLANNED, IN_PROGRESS, PAUSED, COMPLETED, CANCELLED |
leadId | string | No | User ID of a workspace member, from list_members |
startDate, targetDate | string | No | ISO 8601 dates (YYYY-MM-DD) |
update_project
Update a project. Provide at least one field besides projectId; omitted fields are unchanged, and null clears description, leadId and the dates. Requires mcp:write; the same field rules as create_project apply. Webhook subscribers receive project.updated.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Project UUID in this workspace |
name, identifier, description, status, leadId, startDate, targetDate | as above | No | New values |
create_milestone
Add a milestone to a project in this workspace. Requires mcp:write.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Project UUID in this workspace |
name | string | Yes | 1–255 characters |
targetDate | string | No | ISO 8601 date |
sortOrder | number | No | Position among the project's milestones (default 65536) |
update_milestone
Update a milestone of a project in this workspace. Provide at least one field besides milestoneId; null clears targetDate. Requires mcp:write.
| Parameter | Type | Required | Description |
|---|---|---|---|
milestoneId | string | Yes | Milestone UUID, from get_project |
name, targetDate, sortOrder | as above | No | New values |
Deleting projects and milestones, and creating or editing cycles, are not available over MCP. Use the GraphQL API.
list_cycles
List sprint cycles for teams in the workspace.
| Parameter | Type | Required | Description |
|---|---|---|---|
status | string | No | Filter by status: UPCOMING, ACTIVE, COMPLETED |
get_cycle
Get a single cycle with issue counts and completion progress.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Cycle UUID |
Workspace Metadata
list_teams, list_labels, list_statuses, list_members
These tools list workspace metadata. They take no parameters and return arrays of the respective entities with their IDs and names. Use these to resolve IDs before calling other tools. list_labels also returns each label's teamId and parentId.
create_label
Create a label in the connected workspace. Requires mcp:write. As in the app, any current member may. A label with the same name (ignoring case) in the same scope is refused instead of duplicated, and the response names the existing one.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | 1–255 characters |
color | string | Yes | Hex color, #RGB or #RRGGBB |
teamId | string | No | Team UUID in this workspace, to scope the label to a team; omit for a workspace-wide label |
parentId | string | No | UUID of an existing label in this workspace to nest under |
update_label
Rename, recolor or re-parent a label. Provide at least one field besides labelId. A null parentId makes the label top-level; a label cannot be nested under itself or one of its descendants. Requires mcp:write.
| Parameter | Type | Required | Description |
|---|---|---|---|
labelId | string | Yes | Label UUID, from list_labels |
name, color, parentId | as above | No | New values |
Project and label examples
These illustrative tool arguments and decoded results use example IDs. The connection selects the workspace; never add a workspaceId argument. Check isError before using returned IDs.
create_project({ name: "Website refresh", identifier: "WEB", status: "PLANNED" })
// Result (abbreviated):
{ "id": "10000000-0000-4000-8000-000000000001", "name": "Website refresh", "identifier": "WEB", "status": "PLANNED" }
create_label({ name: "Accessibility", color: "#22c55e" })
// Result (abbreviated):
{ "id": "10000000-0000-4000-8000-000000000002", "name": "Accessibility", "color": "#22c55e", "teamId": null, "parentId": null }All six project, milestone and label write tools require current workspace membership and mcp:write. They are unavailable to managed issue runs. Unknown fields, invalid IDs or values, missing update fields, and duplicate identifiers/names return a tool error. Missing and foreign records receive the same not-found response. Database details are withheld. Use list_projects, get_project, list_members, list_teams and list_labels to resolve references first.
Roadmap
list_roadmap_items
List roadmap items in the workspace with optional filters.
| Parameter | Type | Required | Description |
|---|---|---|---|
status | string | No | Filter by status: PLANNED, IN_PROGRESS, COMPLETED, CANCELLED |
category | string | No | Filter by category: FEATURE, IMPROVEMENT, BUG, INFRASTRUCTURE |
versionId | string | No | Filter by roadmap version ID |
limit | number | No | Max results (default 50, max 100) |
create_roadmap_item
Create a new roadmap item. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Item title |
description | string | No | Item description |
status | string | No | Status: PLANNED (default), IN_PROGRESS, COMPLETED, CANCELLED |
category | string | No | Category: FEATURE (default), IMPROVEMENT, BUG, INFRASTRUCTURE |
versionId | string | No | Assign to a roadmap version |
assigneeId | string | No | Assign to a user |
isPublic | string | No | Whether publicly visible ("true"/"false", default "true") |
update_roadmap_item
Update an existing roadmap item. Only provided fields are changed. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Roadmap item UUID |
title | string | No | New title |
description | string | No | New description |
status | string | No | New status |
category | string | No | New category |
versionId | string | No | New version ID (null to unassign) |
assigneeId | string | No | New assignee (null to unassign) |
isPublic | string | No | Whether publicly visible |
delete_roadmap_item
Delete a roadmap item. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Roadmap item UUID |
vote_roadmap_item
Toggle vote on a roadmap item. Votes if not yet voted, unvotes if already voted. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Roadmap item UUID |
list_roadmap_versions
List all roadmap versions (release milestones) with item counts. No parameters required.
create_roadmap_version
Create a new roadmap version. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Version name (e.g., "v2.0") |
description | string | No | Version description |
targetDate | string | No | Target release date (ISO 8601) |
get_roadmap_settings
Get the roadmap settings for the workspace. No parameters required.
Returns: isPublicEnabled, allowSubmissions, allowVoting.
update_roadmap_settings
Update roadmap settings. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
isPublicEnabled | string | No | Enable public roadmap ("true"/"false") |
allowSubmissions | string | No | Allow public submissions ("true"/"false") |
allowVoting | string | No | Allow voting ("true"/"false") |
Workspace & User
list_workspaces
List the authenticated user’s workspaces. OAuth grants return only their connected workspace. No parameters required.
Returns an array of workspaces with: id, name, slug, logoUrl, role, createdAt.
create_workspace
Create a new workspace. The authenticated user becomes the owner. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Workspace display name |
slug | string | Yes | URL-friendly slug (lowercase, hyphens, no spaces) |
logoUrl | string | No | Logo URL for the workspace |
delete_workspace
Permanently delete a workspace and all its data. Only the workspace owner can perform this action. This cannot be undone. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Workspace UUID to delete |
get_workspace
Get details about the current workspace including name, slug, plan, and member/team counts. No parameters required.
update_workspace
Update the current workspace name. Workspace descriptions are unsupported. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | No | New workspace name |
get_current_user
Get the profile of the currently authenticated user. No parameters required.
Returns: id, email, displayName, avatarUrl, createdAt.
update_current_user
Update the current user's profile. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
displayName | string | No | New display name |
avatarUrl | string | No | New avatar URL |
The following three personal-key tools require a connection token. OAuth connections cannot list, create or revoke personal API keys; use Settings → Account → Personal API Keys instead.
list_user_api_keys
List all personal API keys (velu_ prefix) for the current user. No parameters required.
Returns an array of keys with: id, name, keyPrefix, scopes, lastUsedAt, createdAt.
create_user_api_key
Create a personal API key for the current user. The full key is returned once and cannot be retrieved again. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Name for the key (e.g., "CLI Tool") |
scopes | string[] | Yes | Scopes to grant (e.g., user:read, workspaces:list) |
revoke_user_api_key
Revoke a personal API key. This immediately invalidates the key. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | User API key UUID to revoke |
Custom Domains
list_domains
List all custom domains configured for the workspace. No parameters required.
Returns domain name, status (PENDING, VERIFIED, FAILED), CNAME target, and verification details.
add_domain
Add a custom domain. Returns DNS records needed for setup. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | The domain to add (e.g., "issues.example.com") |
Returns setup instructions with two DNS records: (1) a CNAME record pointing to custom.velocity.quest, and (2) a TXT record for domain ownership verification.
verify_domain
Check domain verification status and get setup instructions. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Domain UUID to verify |
remove_domain
Remove a custom domain from the workspace. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Domain UUID to remove |
Claude Agent
transition_issue
Move an issue to a new status by name instead of UUID. Resolves the status name within the issue's team. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
issueId | string | Yes | Issue UUID or identifier (e.g., "ENG-123") |
statusName | string | Yes | Target status name (e.g., "In Progress", "Done") |
get_my_issues
Get issues assigned to the authenticated user with optional status group filter.
| Parameter | Type | Required | Description |
|---|---|---|---|
statusGroup | string | No | Filter by status group: backlog, unstarted, started, completed, cancelled |
limit | number | No | Max results (default 50) |
get_active_sprint
Get the currently active sprint cycle with issue counts and completion progress. No parameters required.
Returns: cycle name, start/end dates, total issues, completed count, progress percentage, and issues breakdown by status.
link_commit
Record a commit SHA against an issue for traceability. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
issueId | string | Yes | Issue UUID or identifier |
commitSha | string | Yes | Git commit SHA |
message | string | No | Commit message |
url | string | No | URL to the commit |
create_branch
Create or reuse a GitHub branch using the issue's project/team repository mapping and the configured branch template. Requires MCP write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
issueId | string | Yes | Issue UUID or identifier |
branchName | string | No | Override the configured naming template |
baseBranch | string | No | Base branch; defaults to the repository default branch |
open_pr
Open or reuse a PR after the branch's changes have been committed and pushed. Links it to the issue through link_pr and applies an optional configured team status. Requires MCP write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
issueId | string | Yes | Issue UUID or identifier |
branchName | string | Yes | Branch containing pushed changes |
baseBranch | string | No | Base branch; defaults to the repository default branch |
title | string | No | Override the issue identifier/title |
summary | string | No | Summary substituted into the PR template |
body | string | No | Override the PR template; the issue link is still included |
draft | boolean | No | Create as a draft (default false) |
Configure templates, mappings and the optional status at Settings → Integrations → GitHub. These tools do not edit files, commit, push, force-update refs or merge PRs. If linking or transition fails, retry open_pr to recover the existing PR.
link_pr
Record a pull request against an issue. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
issueId | string | Yes | Issue UUID or identifier |
prUrl | string | Yes | Pull request URL |
title | string | No | PR title |
status | string | No | PR status: open, merged, closed |
get_issue_context
Get rich context for an issue including comments, activity log, labels, and linked integration events.
The issue object also contains parentId, parent, children and childrenPage, with the same summaries and childrenLimit/childrenOffset parameters as get_issue. Read further pages until issue.childrenPage.hasMore is false.
| Parameter | Type | Required | Description |
|---|---|---|---|
issueId | string | Yes | Issue UUID or identifier |
get_pending_agent_runs
Get pending agent runs for the local_agent tier. Used by the local agent runner to poll for work. No parameters required.
Returns an array of pending runs with: id, trigger_type, trigger_entity_type, trigger_entity_id, metadata, created_at.
get_agent_run_model_settings
Local worker preflight: supply runId to read the effective model policy and issue overrides before claiming a queued run. Does not claim work or change model settings. Requires current member access; running or resumed attempts are bound to their worker connection.
update_agent_run
Update an agent run's status, token counts, and result. Requires mcp:write scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
runId | string | Yes | Agent run UUID |
status | string | No | New status: running, completed, failed, cancelled |
resultSummary | string | No | Summary of the agent's output |
errorMessage | string | No | Error message if failed |
inputTokens | number | No | Total input tokens used |
outputTokens | number | No | Total output tokens used |
model | string | No | Model used for the run |