Protocol requests

Send Authorization: Bearer <access-token>, Content-Type: application/json, and Accept: application/json, text/event-stream to the resource endpoint. Do not put access tokens in URLs.

Legacy initialization, for clients negotiating 2025-11-25:

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

For subsequent legacy requests, include the negotiated MCP-Protocol-Version header. A simple tool request is:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": { "name": "get_workspace", "arguments": {} }
}

The 2026-07-28 protocol carries request metadata. Include matching MCP-Protocol-Version: 2026-07-28, Mcp-Method: tools/call and Mcp-Name: get_workspace headers:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_workspace",
    "arguments": {},
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "caroush-example", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

Use the official MCP client SDK's transport handling where possible. Discovery uses tools/list; the current protocol also supports server/discover. Follow pagination cursors returned by discovery instead of assuming every tool fits in one response.

To create a saved draft through the same API:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "create_text_post",
    "arguments": {
      "caption": "Small consistent steps make a useful routine.",
      "status": "draft",
      "idempotency_key": "33333333-3333-4333-8333-333333333333"
    }
  }
}

This uses the legacy envelope above. Generate your own UUID for a new action, and reuse it only when retrying that same action. For the current protocol, add the metadata and matching headers shown above. The result is a saved draft, not a published social post.