MCP Server API¶

JSON-RPC 2.0 endpoint implementing the Model Context Protocol (MCP 2025-11-25). Connect AI clients to Vellocity's content generation, analytics, and GTM tools.

Endpoint: https://api.vell.ai/api/v1/mcp Authentication: OAuth 2.1 Bearer token Protocol: JSON-RPC 2.0 over Streamable HTTP

Transport¶

Method	Path	Purpose
`POST`	`/api/v1/mcp`	Send JSON-RPC requests
`GET`	`/api/v1/mcp`	Subscribe to SSE change notifications
`DELETE`	`/api/v1/mcp`	Terminate session

Request Headers¶

Content-Type: application/json
Authorization: Bearer YOUR_OAUTH_TOKEN
Mcp-Session-Id: <session-id>
Accept: application/json

SSE streaming

Set Accept: text/event-stream on POST requests to receive responses as Server-Sent Events instead of JSON. Required for long-running tool calls.

Session Lifecycle¶

sequenceDiagram
    participant Client
    participant MCP as MCP Server

    Client->>MCP: POST /mcp (initialize)
    MCP-->>Client: capabilities + Mcp-Session-Id header
    Client->>MCP: POST /mcp (tools/list)
    Note over Client,MCP: Include Mcp-Session-Id on all subsequent requests
    MCP-->>Client: Available tools
    Client->>MCP: POST /mcp (tools/call)
    MCP-->>Client: Tool result
    Client->>MCP: DELETE /mcp
    MCP-->>Client: 204 No Content

Initialize¶

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "clientInfo": { "name": "my-app", "version": "1.0" },
    "capabilities": {}
  }
}

Response (includes Mcp-Session-Id in response header):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "serverInfo": { "name": "vellocity-mcp", "version": "1.0.0" },
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": { "listChanged": true },
      "prompts": { "listChanged": true }
    }
  }
}

Methods¶

tools/list¶

List available tools. The server exposes 17 tools (see Available tools below), returned 10 per page with cursor-based pagination — follow nextCursor to fetch the rest.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": { "cursor": null }
}

Response (truncated — nextCursor returns the remaining tools):

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "execute_capability",
        "description": "Execute an AI content capability",
        "inputSchema": {
          "type": "object",
          "properties": {
            "slug": { "type": "string" },
            "settings": { "type": "object" }
          },
          "required": ["slug"]
        }
      }
    ],
    "nextCursor": "djE6MTA="
  }
}

tools/call¶

Execute a tool.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "execute_capability",
    "arguments": {
      "slug": "generate-blog-post",
      "settings": { "topic": "Cloud cost optimization" }
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      { "type": "text", "text": "Execution started. ID: 789" }
    ],
    "isError": false
  }
}

Available tools¶

The server exposes 17 tools, each a thin adapter onto an existing Vellocity REST endpoint — the McpToolDispatcher translates tools/call arguments into the corresponding controller action, which remains the source of truth for validation, authorization, and the exact parameter shape. The groups below are logical; all 17 are returned by tools/list.

Call any of them with tools/call, passing name and arguments (the example under tools/call uses execute_capability).

Capabilities¶

Tool	Purpose	Key arguments
`list_capabilities`	List the AI capabilities available to you	—
`get_capability`	Get a single capability's detail	`slug`
`execute_capability`	Run a capability (content generation, analysis, GTM action)	`slug` (+ capability-specific settings)

Executions¶

Tool	Purpose	Key arguments
`list_executions`	List your capability executions	—
`get_execution`	Get one execution's status/result	`id`
`get_execution_assets`	Get the assets produced by an execution	`id`

Kanban & content¶

Tool	Purpose	Key arguments
`get_kanban`	Get the content kanban board	—
`move_content`	Move a single content item to another column/stage	`content_id`
`bulk_move_content`	Move multiple content items at once	—

Brand voices¶

Tool	Purpose	Key arguments
`list_brand_voices`	List your brand voices	—
`get_brand_voice`	Get one brand voice	`id`

Agents¶

Tool	Purpose	Key arguments
`list_agents`	List your GTM agents	—
`get_agent`	Get one agent	`id`

Partner health¶

Tool	Purpose	Key arguments
`get_partner_health`	Current partner health score(s)	—
`get_partner_health_history`	Partner health score over time	—
`get_partner_health_summary`	Aggregated partner health summary	—
`get_partner_health_at_risk`	Partners flagged at risk	—

Source of truth

Exact parameters and response shapes are defined by the REST endpoints these tools wrap — the McpToolDispatcher (App\Services\Mcp\McpToolDispatcher) only maps tool name → controller action and route parameters. Read-only tools dispatch as GET; execute_capability, move_content, and bulk_move_content dispatch as POST. Use tools/list to discover the live inputSchema for any tool rather than hard-coding arguments.

resources/list¶

List available vellocity:// resources.

resources/read¶

Read a specific resource by URI.

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/read",
  "params": { "uri": "vellocity://brand-voices/1" }
}

resources/templates/list¶

List 5 URI templates for dynamic resource access.

prompts/list¶

List 4 available prompt templates.

prompts/get¶

Get a prompt template with populated messages.

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "prompts/get",
  "params": { "name": "content-brief", "arguments": { "topic": "SaaS pricing" } }
}

ping¶

{ "jsonrpc": "2.0", "id": 6, "method": "ping" }

Returns { "jsonrpc": "2.0", "id": 6, "result": {} }

SSE Stream (Change Notifications)¶

GET /api/v1/mcp
Accept: text/event-stream

Subscribe to real-time notifications when server lists change:

event: endpoint
data: /api/v1/mcp

event: message
data: {"jsonrpc":"2.0","method":"notifications/tools/list_changed"}

event: heartbeat
data: {"timestamp":"2026-02-26T10:00:30Z","session_id":"abc123"}

Event	Frequency	Description
`endpoint`	Once	Initial connection confirmation
`message`	On change	`notifications/tools/list_changed`, `notifications/resources/list_changed`, or `notifications/prompts/list_changed`
`heartbeat`	~30 seconds	Keep-alive signal

The stream auto-terminates after 5 minutes. Reconnect to continue receiving notifications.

Authorization¶

Two-layer authorization model:

Layer 1: OAuth 2.1 Scopes¶

Scope	Access
`mcp:full`	All MCP capabilities
`mcp:tools`	`tools/list` and `tools/call`
`mcp:tools:read`	`tools/list` only
`mcp:tools:write`	`tools/call` only
`mcp:resources`	`resources/list` and `resources/read`
`mcp:prompts`	`prompts/list` and `prompts/get`

Layer 2: Team Capabilities¶

Even with a valid scope, the user's team role must permit the action (e.g., manage_content for content tools, view_companies for analytics).

Error Codes¶

Code	Name	Description
`-32700`	Parse Error	Invalid JSON
`-32600`	Invalid Request	Missing `jsonrpc` or `method`
`-32601`	Method Not Found	Unknown method name
`-32602`	Invalid Params	Missing required parameters
`-32603`	Internal Error	Insufficient scope or server error

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32601,
    "message": "Method not found: tools/invalid"
  }
}

Use Cases¶

Connect Claude Desktop to Vellocity¶

Generate an OAuth token with mcp:full scope
Configure Claude Desktop's MCP settings to point to https://api.vell.ai/api/v1/mcp
Claude can now list and execute Vellocity tools, read resources, and use prompts

Build a Custom MCP Client¶

Send initialize to establish a session
Call tools/list to discover available capabilities
Use tools/call to execute content generation, analytics, or workflow actions
Subscribe to SSE for real-time tool list updates