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.

ParameterTypeRequiredDescription
cursorstringNoPrevious nextCursor; omit for retained history
limitnumberNo1–100 events, default 50
sourcesstring[]NoOptional 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.

ParameterTypeRequiredDescription
projectIdstringNoFilter by project ID
statusIdstringNoFilter by status ID
prioritystringNoFilter by priority: URGENT, HIGH, MEDIUM, LOW, NONE
assigneeIdstringNoFilter by assignee user ID
labelIdstringNoFilter by label ID
limitnumberNoMax results (default 50, max 50)
offsetnumberNoOffset 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.

ParameterTypeRequiredDescription
issueIdstringYesIssue UUID or identifier (e.g., "ENG-123")
childrenLimitintegerNoDirect children per page, 1–50; default 50
childrenOffsetintegerNoOffset, 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.

ParameterTypeRequiredDescription
titlestringYesIssue title
descriptionstringNoIssue description (plain text, Markdown, or HTML). Markdown is automatically rendered as rich text in the UI.
teamIdstringYesTeam ID to create the issue in
projectIdstringNoProject ID to assign to
prioritystringNoPriority: URGENT, HIGH, MEDIUM, LOW, NONE
statusIdstringNoStatus ID (defaults to team's default status)
assigneeIdstringNoUser ID to assign
parentIdstringNoParent issue UUID or identifier
userStoryIdstringNoStory UUID or US identifier in this workspace
labelIdsstring[]NoLabel 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.

ParameterTypeRequiredDescription
issueIdstringYesIssue UUID to update
titlestringNoNew title
descriptionstringNoNew description (plain text, Markdown, or HTML). Markdown is automatically rendered as rich text in the UI.
prioritystringNoNew priority
statusIdstringNoNew status ID
assigneeIdstringNoNew assignee (null to unassign)

search_issues

Full-text search across issue titles, descriptions, and identifiers.

ParameterTypeRequiredDescription
querystringYesSearch query string
limitnumberNoMax results (default 20, max 50)

add_comment

Add a comment to an issue. Requires mcp:write scope.

ParameterTypeRequiredDescription
issueIdstringYesIssue UUID to comment on
bodystringYesComment text (plain text or markdown)
parentIdstringNoParent comment ID for threaded replies

list_comments

List all comments on an issue, ordered by creation date.

ParameterTypeRequiredDescription
issueIdstringYesIssue 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.

ToolArgumentsBehavior
list_prdsstatus[], projectId, teamId, limit, offsetFilter and page PRDs.
get_prdprdIdBody, requirements, coverage and progress.
list_user_storiesprdId, status[], teamId, projectId, limit, offsetFilter and page stories.
get_user_storystoryIdStory, acceptance criteria, requirements and issue progress.
create_prdinputCreate a draft; accepts the proposed draft unchanged, including requirements.
update_prdprdId, input, expectedUpdatedAt?Edit title, summary, content or owner; content edits reopen approved PRDs for review.
set_prd_statusprdId, statusDRAFT, IN_REVIEW or ARCHIVED. Human approval stays in Velocity.
create_prd_requirementprdId, inputAdd a titled requirement; optional description, type and priority.
update_prd_requirementprdId, requirementId, inputEdit a requirement by UUID or R key.
create_user_storyinput, prdId?Accept a proposal unchanged; resolve requirementKeys within its PRD.
update_user_storystoryId, inputEdit story fields and optionally replace requirementIds or requirementKeys.
split_user_storystoryId, pattern, children[]Apply a reviewed split; keep pattern and child proposals unchanged.
create_issues_from_storiesitems[]Add storyId and teamId to each reviewed issue proposal. Reuses ordinary creation, events, embeddings and triage.
link_issue_to_storyissueId, storyIdLink existing work to its story.
propose_prddescription, step?, answers?, feedback?, projectIds?, teamIds?Clarify or draft (default); returns proposals only.
propose_storiesprdId, requirementKeys?, step?Estimate or generate (default); INVEST, duplicate flags and coverage.
check_storystoryIdINVEST assessment and proposed edits.
propose_story_splitstoryId, pattern?Proposed children and verified criterion mapping.
propose_issues_for_storystoryId, 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.

ToolArgumentsResult
prepare_issue_attachmentRequired: issueId, uploadId (UUID), name, contentTypeResolved issue/upload IDs and credential-free binary API instructions; preparation alone uploads nothing. Requires mcp:write.
upload_issue_attachmentRequired: 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_attachmentsRequired: issueIdUp to 50 ready files ordered by creation time and ID.
get_issue_attachmentRequired: 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_attachmentRequired: 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.

ParameterTypeRequiredDescription
statusstringNoFilter by status: BACKLOG, PLANNED, IN_PROGRESS, PAUSED, COMPLETED, CANCELLED

get_project

Get detailed information about a project including milestones and issue count.

ParameterTypeRequiredDescription
projectIdstringYesProject 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.

ParameterTypeRequiredDescription
namestringYes1–255 characters
identifierstringYes1–10 letters and digits, starting with a letter, unique in the workspace (for example WEB or API2). Lowercase is uppercased.
descriptionstringNoPlain text, up to 10,000 characters
statusstringNoBACKLOG (default), PLANNED, IN_PROGRESS, PAUSED, COMPLETED, CANCELLED
leadIdstringNoUser ID of a workspace member, from list_members
startDate, targetDatestringNoISO 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.

ParameterTypeRequiredDescription
projectIdstringYesProject UUID in this workspace
name, identifier, description, status, leadId, startDate, targetDateas aboveNoNew values

create_milestone

Add a milestone to a project in this workspace. Requires mcp:write.

ParameterTypeRequiredDescription
projectIdstringYesProject UUID in this workspace
namestringYes1–255 characters
targetDatestringNoISO 8601 date
sortOrdernumberNoPosition 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.

ParameterTypeRequiredDescription
milestoneIdstringYesMilestone UUID, from get_project
name, targetDate, sortOrderas aboveNoNew 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.

ParameterTypeRequiredDescription
statusstringNoFilter by status: UPCOMING, ACTIVE, COMPLETED

get_cycle

Get a single cycle with issue counts and completion progress.

ParameterTypeRequiredDescription
idstringYesCycle 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.

ParameterTypeRequiredDescription
namestringYes1–255 characters
colorstringYesHex color, #RGB or #RRGGBB
teamIdstringNoTeam UUID in this workspace, to scope the label to a team; omit for a workspace-wide label
parentIdstringNoUUID 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.

ParameterTypeRequiredDescription
labelIdstringYesLabel UUID, from list_labels
name, color, parentIdas aboveNoNew 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.

ParameterTypeRequiredDescription
statusstringNoFilter by status: PLANNED, IN_PROGRESS, COMPLETED, CANCELLED
categorystringNoFilter by category: FEATURE, IMPROVEMENT, BUG, INFRASTRUCTURE
versionIdstringNoFilter by roadmap version ID
limitnumberNoMax results (default 50, max 100)

create_roadmap_item

Create a new roadmap item. Requires mcp:write scope.

ParameterTypeRequiredDescription
titlestringYesItem title
descriptionstringNoItem description
statusstringNoStatus: PLANNED (default), IN_PROGRESS, COMPLETED, CANCELLED
categorystringNoCategory: FEATURE (default), IMPROVEMENT, BUG, INFRASTRUCTURE
versionIdstringNoAssign to a roadmap version
assigneeIdstringNoAssign to a user
isPublicstringNoWhether publicly visible ("true"/"false", default "true")

update_roadmap_item

Update an existing roadmap item. Only provided fields are changed. Requires mcp:write scope.

ParameterTypeRequiredDescription
idstringYesRoadmap item UUID
titlestringNoNew title
descriptionstringNoNew description
statusstringNoNew status
categorystringNoNew category
versionIdstringNoNew version ID (null to unassign)
assigneeIdstringNoNew assignee (null to unassign)
isPublicstringNoWhether publicly visible

delete_roadmap_item

Delete a roadmap item. Requires mcp:write scope.

ParameterTypeRequiredDescription
idstringYesRoadmap item UUID

vote_roadmap_item

Toggle vote on a roadmap item. Votes if not yet voted, unvotes if already voted. Requires mcp:write scope.

ParameterTypeRequiredDescription
idstringYesRoadmap 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.

ParameterTypeRequiredDescription
namestringYesVersion name (e.g., "v2.0")
descriptionstringNoVersion description
targetDatestringNoTarget 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.

ParameterTypeRequiredDescription
isPublicEnabledstringNoEnable public roadmap ("true"/"false")
allowSubmissionsstringNoAllow public submissions ("true"/"false")
allowVotingstringNoAllow 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.

ParameterTypeRequiredDescription
namestringYesWorkspace display name
slugstringYesURL-friendly slug (lowercase, hyphens, no spaces)
logoUrlstringNoLogo 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.

ParameterTypeRequiredDescription
idstringYesWorkspace 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.

ParameterTypeRequiredDescription
namestringNoNew 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.

ParameterTypeRequiredDescription
displayNamestringNoNew display name
avatarUrlstringNoNew 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.

ParameterTypeRequiredDescription
namestringYesName for the key (e.g., "CLI Tool")
scopesstring[]YesScopes 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.

ParameterTypeRequiredDescription
idstringYesUser 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.

ParameterTypeRequiredDescription
domainstringYesThe 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.

ParameterTypeRequiredDescription
idstringYesDomain UUID to verify

remove_domain

Remove a custom domain from the workspace. Requires mcp:write scope.

ParameterTypeRequiredDescription
idstringYesDomain 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.

ParameterTypeRequiredDescription
issueIdstringYesIssue UUID or identifier (e.g., "ENG-123")
statusNamestringYesTarget status name (e.g., "In Progress", "Done")

get_my_issues

Get issues assigned to the authenticated user with optional status group filter.

ParameterTypeRequiredDescription
statusGroupstringNoFilter by status group: backlog, unstarted, started, completed, cancelled
limitnumberNoMax 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.

ParameterTypeRequiredDescription
issueIdstringYesIssue UUID or identifier
commitShastringYesGit commit SHA
messagestringNoCommit message
urlstringNoURL 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.

ParameterTypeRequiredDescription
issueIdstringYesIssue UUID or identifier
branchNamestringNoOverride the configured naming template
baseBranchstringNoBase 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.

ParameterTypeRequiredDescription
issueIdstringYesIssue UUID or identifier
branchNamestringYesBranch containing pushed changes
baseBranchstringNoBase branch; defaults to the repository default branch
titlestringNoOverride the issue identifier/title
summarystringNoSummary substituted into the PR template
bodystringNoOverride the PR template; the issue link is still included
draftbooleanNoCreate 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.

ParameterTypeRequiredDescription
issueIdstringYesIssue UUID or identifier
prUrlstringYesPull request URL
titlestringNoPR title
statusstringNoPR 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.

ParameterTypeRequiredDescription
issueIdstringYesIssue 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.

ParameterTypeRequiredDescription
runIdstringYesAgent run UUID
statusstringNoNew status: running, completed, failed, cancelled
resultSummarystringNoSummary of the agent's output
errorMessagestringNoError message if failed
inputTokensnumberNoTotal input tokens used
outputTokensnumberNoTotal output tokens used
modelstringNoModel used for the run