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. Returns 10 tools per page with cursor-based pagination.

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

Response:

{
  "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
  }
}

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