MCP Setup & Auth

Generate an API key and connect your AI agent to Velocity.

Generate an API Key

1

Navigate to API Keys

Go to Settings → API Keys in your Velocity workspace.

2

Create a new key

Click New API Key. Give it a descriptive name like “Claude MCP” and select the scopes you need. For full MCP access, enable issues:read,issues:write, projects:read, and projects:write.

3

Copy the key

The full API key (prefixed with vel_mcp_) is shown once. Copy it immediately — it cannot be retrieved later. The key is stored as a SHA-256 hash.

Configure Claude Code

Add the Velocity MCP server to your Claude Code configuration:

{
  "mcpServers": {
    "velocity": {
      "url": "https://app.velocity.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer vel_mcp_your_key_here",
        "X-Workspace-Slug": "your-workspace"
      }
    }
  }
}

Configure Claude Desktop

For Claude Desktop, add the server to your claude_desktop_config.json:

{
  "mcpServers": {
    "velocity": {
      "url": "https://app.velocity.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer vel_mcp_your_key_here",
        "X-Workspace-Slug": "your-workspace"
      }
    }
  }
}

Configure Cursor

In Cursor, open settings and navigate to the MCP section. Add a new server with:

  • Name: Velocity
  • URL: https://app.velocity.dev/api/mcp
  • Headers: Authorization and X-Workspace-Slug as above

Authentication

The MCP server authenticates using the Authorization: Bearer header. The API key is validated against SHA-256 hashes stored in the database. Each key has scoped permissions — the server will reject requests that exceed the key's authorized scopes.

Rate Limits

MCP connections are rate-limited to 300 requests per minute per API key. This uses a sliding window algorithm. If you exceed the limit, requests return a 429 status with a Retry-After header.

Security Best Practice

Create a dedicated API key for each AI agent with the minimum required scopes. Avoid sharing keys between agents or using workspace admin keys for MCP.