Vellocity MCP API Reference¶

Model Context Protocol (MCP) server for AI-powered content workflow automation.

Connect any MCP-compatible AI client to Vellocity's content engine — generate, review, and publish content through a standardized protocol with real-time change notifications.

Marketplace Listing¶

Short Description¶

AI-powered content workflow server with native MCP support. Generate, review, and publish content at scale through 13 tools, live resources, prompt templates, and real-time SSE notifications — all accessible from any MCP-compatible AI client.

Long Description¶

Vellocity's MCP server exposes your entire content workflow as a programmable API that any AI client can connect to using the Model Context Protocol (MCP) 2025-11-25 specification.

What you get:

13 tools spanning content generation, execution tracking, kanban workflow management, brand voice configuration, and AI agent orchestration — each with structured input/output schemas
10 live resources accessible via the vellocity:// URI scheme — read brand voices, capabilities, executions, kanban state, and agent configurations as structured data
4 prompt templates that guide AI clients through multi-step workflows — from executing a capability to generating brand briefs and reviewing content
Real-time notifications delivered via Server-Sent Events — clients are instantly notified when tools, resources, or prompts change so they can refresh their view
Two-layer authorization combining OAuth 2.1 scopes with team member capabilities, giving you fine-grained control over what each token and user can access
Streamable HTTP transport with JSON-RPC 2.0 — works with any HTTP client, no WebSockets or special infrastructure required

Whether you're building an AI assistant that drafts blog posts, an automation pipeline that moves content through review stages, or a dashboard that monitors execution health — the MCP server gives your AI clients a complete, permission-aware interface to Vellocity's content engine.

Highlights¶

Connect any MCP-compatible AI client — Claude, GPT, Cursor, or custom agents — to your Vellocity content workflow
13 tools with structured schemas for content generation, kanban management, brand voices, and AI agent orchestration
Real-time SSE notifications alert connected clients when available tools, resources, or prompts change
Two-layer authorization (OAuth 2.1 scopes + team capabilities) ensures each client sees only what it should
4 guided prompt templates automate multi-step workflows like execute-workflow, content-review, and brand-brief generation

Quick Start¶

1. Initialize¶

POST /api/v1/mcp
Content-Type: application/json
Authorization: Bearer <your-token>

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

The server responds with its capabilities and a session ID:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "tools":     { "listChanged": true },
      "resources": { "subscribe": false, "listChanged": true },
      "prompts":   { "listChanged": true }
    },
    "serverInfo": {
      "name": "vellocity-content-workflow",
      "version": "2.1.0"
    }
  }
}

Save the Mcp-Session-Id response header — include it on all subsequent requests.

2. Discover Tools¶

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

3. Call a Tool¶

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 3,
  "params": {
    "name": "list_capabilities",
    "arguments": { "category": "generation" }
  }
}

4. Listen for Changes (optional)¶

Open an SSE stream to receive real-time notifications:

GET /api/v1/mcp
Accept: text/event-stream
Mcp-Session-Id: <session-id>
Authorization: Bearer <your-token>

The server will push notifications/tools/list_changed, notifications/resources/list_changed, and notifications/prompts/list_changed events when lists change, so your client can re-fetch.

Transport¶

The MCP server uses Streamable HTTP transport with JSON-RPC 2.0 messaging.

Method	Endpoint	Purpose
`POST`	`/api/v1/mcp`	Send JSON-RPC requests and notifications
`GET`	`/api/v1/mcp`	Open SSE stream for server-initiated messages
`DELETE`	`/api/v1/mcp`	Terminate a session

Headers:

Header	Required	Description
`Content-Type`	POST	Must be `application/json`
`Accept`	GET, optional on POST	`text/event-stream` for SSE streaming
`Authorization`	All	`Bearer <token>`
`Mcp-Session-Id`	After initialize	Session ID from initialize response

SSE streaming on POST: Add Accept: text/event-stream to POST requests to receive responses as SSE events instead of JSON. Useful for long-running tool calls.

Tools¶

Content Generation¶

Tool	Type	Description
`list_capabilities`	Read	Discover available AI capabilities. Filter by category: generation, publishing, analysis, workflow.
`get_capability`	Read	Get details for a specific capability — required settings, credit cost, extensions.
`execute_capability`	Write	Start an AI capability execution. Returns an execution ID to track progress.

Execution Tracking¶

Tool	Type	Description
`list_executions`	Read	List executions with filters: status, agent, priority, date range. Paginated.
`get_execution`	Read	Full execution details — plan, step results, generated assets, errors.
`get_execution_assets`	Read	Content items generated by an execution — raw assets and resolved records.

Kanban Workflow¶

Tool	Type	Description
`get_kanban`	Read	Kanban board state — content grouped by columns: Generated, In Review, Ready, Published.
`move_content`	Write	Move a content item to a different kanban column.
`bulk_move_content`	Write	Move up to 100 content items to the same column at once.

Brand Voices¶

Tool	Type	Description
`list_brand_voices`	Read	All brand voices — tone, style, industry, target audience.
`get_brand_voice`	Read	Full brand voice details including associated products.

AI Agents¶

Tool	Type	Description
`list_agents`	Read	Available AI agents — capabilities, model, success rate.
`get_agent`	Read	Full agent configuration — settings, guardrails, timeout, memory.

Tool Annotations¶

Every tool includes MCP annotations that help AI clients make safe decisions:

Annotation	Meaning
`readOnlyHint: true`	Tool only reads data, never modifies
`destructiveHint: false`	Tool does not delete or destroy data
`idempotentHint: true`	Calling the tool multiple times with the same input produces the same result

All read tools are readOnlyHint: true. Write tools (execute_capability, move_content, bulk_move_content) are readOnlyHint: false. No tools are destructive.

Resources¶

Resources provide direct read access to Vellocity data through the vellocity:// URI scheme. All resources return application/json.

Static Resources¶

URI	Name	Description
`vellocity://capabilities`	All Capabilities	Complete list of AI capabilities with categories and credit costs
`vellocity://kanban`	Kanban Board	Current kanban state — all columns and content items
`vellocity://executions`	Recent Executions	Recent capability executions for the current user
`vellocity://brand-voices`	Brand Voices	Brand voice configurations for the current company
`vellocity://agents`	AI Agents	Available agents and their configurations

URI Templates¶

For individual records, use URI templates with an ID or slug:

URI Template	Name	Description
`vellocity://capabilities/{slug}`	Capability Detail	Settings, credit cost, and extensions for one capability
`vellocity://executions/{id}`	Execution Detail	Plan, step results, and generated assets for one execution
`vellocity://content/{id}`	Content Item	Full text and metadata for a kanban content item
`vellocity://brand-voices/{id}`	Brand Voice Detail	Tone, audience, products for one brand voice
`vellocity://agents/{id}`	Agent Detail	Configuration and performance metrics for one agent

Reading a Resource¶

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

Prompts¶

Prompt templates guide AI clients through multi-step workflows. Each prompt returns structured messages that the client can use to orchestrate tool calls.

execute-workflow¶

Guide through selecting and executing an AI capability.

Argument	Required	Description
`goal`	Yes	What you want to accomplish (e.g., "Generate a blog post about cloud security")
`category`	No	Filter capabilities: generation, publishing, analysis, workflow
`brand_voice_id`	No	Brand voice ID for content generation context

Workflow: Discovers capabilities, recommends the best match, configures settings, and starts the execution.

content-review¶

Review content items on the kanban board.

Argument	Required	Description
`status`	No	Filter by kanban column: generated, review, ready, published
`limit`	No	Maximum items to review (default: 10)

Workflow: Loads kanban board, assesses quality, suggests next actions for each item.

brand-brief¶

Generate a structured brand brief for content creation.

Argument	Required	Description
`brand_voice_id`	Yes	Brand voice to build the brief from
`content_type`	No	Type of content being created (blog post, email, social media)
`target_audience`	No	Override or refine the brand voice target audience

Workflow: Loads brand voice, builds brief covering identity, tone, audience, and key messaging.

execution-report¶

Summarize execution results and metrics.

Argument	Required	Description
`execution_id`	Yes	Execution ID to summarize
`include_assets`	No	Include generated asset details (default: true)

Workflow: Loads execution, optionally loads assets, summarizes status, credits, duration, and issues.

Getting a Prompt¶

{
  "jsonrpc": "2.0",
  "method": "prompts/get",
  "id": 6,
  "params": {
    "name": "execute-workflow",
    "arguments": {
      "goal": "Generate a blog post about cloud security",
      "category": "generation"
    }
  }
}

Authorization¶

Vellocity uses two-layer authorization for fine-grained access control.

Layer 1 — OAuth 2.1 Scopes¶

Scopes control what the token can access at the protocol level.

Scope	Access
`mcp:full`	All tools, resources, and prompts
`mcp:tools`	All tools (read + write)
`mcp:tools:read`	Read-only tools only (10 tools)
`mcp:tools:write`	All tools including write operations
`mcp:resources`	Resources list, read, and templates
`mcp:prompts`	Prompt list and get

Tokens without MCP-specific scopes default to mcp:full for backwards compatibility.

Layer 2 — Team Capabilities¶

Team capabilities control what the user can do within their organization.

Capability	Grants Access To
`MANAGE_CONTENT`	execute_capability, kanban tools, execution tools, agent tools
`VIEW_ANALYTICS`	Execution list and detail tools
`VIEW_COMPANIES`	Brand voice tools
`MANAGE_COMPANIES`	Brand voice tools
`API_ACCESS`	Agent tools

Both layers must allow access for a tool, resource, or prompt to be visible. Items that fail either check are filtered from list responses, and direct calls are rejected with a scope error.

Permission Summary¶

The initialize response includes a _meta.permissions object showing what the current token and user can access:

{
  "scopes": ["mcp:full"],
  "tools_access": true,
  "resources_access": true,
  "prompts_access": true,
  "team_capabilities": ["MANAGE_CONTENT", "VIEW_COMPANIES"]
}

Real-Time Notifications¶

The server pushes listChanged notifications over the SSE stream when available tools, resources, or prompts change.

How It Works¶

Client opens an SSE stream: GET /api/v1/mcp with Accept: text/event-stream
Server sends an initial endpoint event with the POST URL
Server polls for changes every 2 seconds
When a list changes, the server sends a JSON-RPC notification:

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

Client should re-call tools/list, resources/list, or prompts/list to get updated data

Notification Types¶

Notification	Trigger
`notifications/tools/list_changed`	Capabilities added, removed, or reconfigured
`notifications/resources/list_changed`	Brand voices, agents, or content items created/updated/deleted
`notifications/prompts/list_changed`	Prompt templates updated

Stream Lifecycle¶

Heartbeats are sent every 30 seconds to keep the connection alive
Maximum lifetime is 5 minutes — clients should reconnect after
Graceful close — the stream ends cleanly when the lifetime expires

Pagination¶

tools/list uses cursor-based pagination (10 tools per page). If more tools are available, the response includes a nextCursor:

{
  "result": {
    "tools": [ /* ... 10 tools ... */ ],
    "nextCursor": "djE6MTA="
  }
}

Pass the cursor on the next request:

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 7,
  "params": { "cursor": "djE6MTA=" }
}

Session Management¶

Sessions are established during initialize and are stateless on the server.

Initialize — server generates an Mcp-Session-Id and returns it in the response header
Subsequent requests — client includes Mcp-Session-Id header
Terminate — DELETE /api/v1/mcp cleanly ends the session (returns 204)

Sessions do not store state on the server — the ID is used for request correlation and SSE stream binding.

Error Handling¶

Errors follow the JSON-RPC 2.0 error codes:

Code	Meaning	When
`-32700`	Parse error	Invalid JSON in request body
`-32600`	Invalid request	Missing `jsonrpc: "2.0"` or `method`
`-32601`	Method not found	Unknown method name
`-32602`	Invalid params	Missing required params, bad cursor, unknown tool/prompt
`-32603`	Internal error	Insufficient scope or permissions

Tool execution errors return a valid result with isError: true:

{
  "result": {
    "content": [{ "type": "text", "text": "..." }],
    "isError": true
  }
}

Protocol Compliance¶

Spec Requirement	Status
MCP 2025-11-25 protocol version	Supported
JSON-RPC 2.0 envelope	Full compliance
Streamable HTTP transport	POST, GET, DELETE
SSE streaming on POST	Via Accept header
Batch requests	Supported
Notifications (no response)	202 Accepted
Cursor-based pagination	tools/list
Tool annotations	readOnlyHint, destructiveHint, idempotentHint
Output schemas	All 13 tools
Resource URI templates	5 templates
listChanged notifications	tools, resources, prompts
Session management	Mcp-Session-Id header