MCP Server
Connect AI agents to Velocity via the Model Context Protocol.
What is MCP?
The Model Context Protocol (MCP) is an open standard that lets AI agents interact with external tools through a unified interface. Velocity includes a built-in MCP server that exposes 46 tools for issue tracking, project management, workspace and user management, roadmap planning, custom domains, Claude agent coordination, and more.
AI agents like Claude (via Claude Code or Claude Desktop), Cursor, Windsurf, and other MCP-compatible clients can connect to Velocity and create issues, search tasks, update statuses, manage projects, plan roadmaps, and configure domains — all without leaving their workflow.
Use Cases
- AI coding assistants — create bug reports directly from code reviews
- Automated triage — agents categorize and prioritize incoming issues
- Status updates — agents update issue progress as they complete work
- Search & context — agents find related issues to inform their work
- Project management — agents create projects, cycles, and milestones
- Roadmap planning — agents manage roadmap items, versions, and voting
- Domain management — agents add and verify custom domains
- AI agent coordination — Claude agents process issues, link commits, and track sprint progress
Available Tools
Issue Tracking
| Tool | Scope | Description |
|---|
list_issues | read | List issues with filters for project, status, priority, assignee, label |
get_issue | read | Get full details of an issue by ID or identifier (e.g., ENG-123) |
create_issue | write | Create a new issue with title, description, priority, status |
update_issue | write | Update an existing issue's fields |
search_issues | read | Full-text search across issue titles and descriptions |
add_comment | write | Add a comment to an issue |
list_comments | read | List all comments on an issue |
Projects & Cycles
| Tool | Scope | Description |
|---|
list_projects | read | List all projects with optional status filter |
get_project | read | Get project details including milestones and issue count |
list_cycles | read | List sprint cycles with optional status filter |
get_cycle | read | Get cycle details with issue counts and progress |
Workspace Metadata
| Tool | Scope | Description |
|---|
list_teams | read | List all teams in the workspace |
list_labels | read | List all available labels |
list_statuses | read | List all issue statuses across teams |
list_members | read | List workspace members with roles |
Roadmap
| Tool | Scope | Description |
|---|
list_roadmap_items | read | List roadmap items with status, category, and version filters |
create_roadmap_item | write | Create a new roadmap item |
update_roadmap_item | write | Update an existing roadmap item |
delete_roadmap_item | write | Delete a roadmap item |
vote_roadmap_item | write | Toggle vote on a roadmap item |
list_roadmap_versions | read | List all roadmap versions (releases) |
create_roadmap_version | write | Create a new roadmap version |
get_roadmap_settings | read | Get roadmap visibility and voting settings |
update_roadmap_settings | write | Update roadmap settings |
Workspace & User
| Tool | Scope | Description |
|---|
list_workspaces | read | List all workspaces the user belongs to |
create_workspace | write | Create a new workspace (user becomes owner) |
delete_workspace | write | Permanently delete a workspace (owner only) |
get_workspace | read | Get current workspace details (name, plan, member count) |
update_workspace | write | Update workspace name or description |
get_current_user | read | Get the authenticated user's profile |
update_current_user | write | Update user display name or avatar |
list_user_api_keys | read | List personal API keys (velu_ prefix) |
create_user_api_key | write | Create a personal API key (returns key once) |
revoke_user_api_key | write | Revoke a personal API key |
Custom Domains
| Tool | Scope | Description |
|---|
list_domains | read | List custom domains with verification status |
add_domain | write | Add a custom domain with DNS setup instructions |
verify_domain | write | Check domain verification status |
remove_domain | write | Remove a custom domain |
Claude Agent
| Tool | Scope | Description |
|---|
transition_issue | write | Move issue to a status by name (e.g., "In Progress") instead of UUID |
get_my_issues | read | Get issues assigned to the authenticated user, filtered by status group |
get_active_sprint | read | Get the active cycle with issue counts and progress |
link_commit | write | Record a commit SHA against an issue |
link_pr | write | Record a pull request URL against an issue |
get_issue_context | read | Rich issue context: comments, activities, labels, linked events |
get_pending_agent_runs | read | Get pending agent runs for local_agent tier |
update_agent_run | write | Update an agent run's status, tokens, and result |
Resources
The MCP server also exposes these read-only resources for quick context:
| URI | Description |
|---|
velocity://workspace | Workspace metadata (name, slug, plan, member/team counts) |
velocity://issues | Recent issues (last 20, sorted by update time) |
velocity://projects | All projects with status and progress |
velocity://roadmap | Roadmap items, versions, and settings overview |
velocity://domains | Custom domains with verification status |
Scopes
MCP tools require appropriate scopes on the API key:
mcp:read — Access to all read-only tools and resourcesmcp:write — Access to create/update/delete tools (also requires mcp:read)mcp:admin — Full access including settings management
Next Steps