MCP server

The Ritual MCP server lets coding agents and custom MCP clients pull exploration context, recommendations, build briefs, and the workspace knowledge graph into their session over HTTPS using the Model Context Protocol.

If you’re using a supported coding agent (Claude Code, Cursor, Windsurf, Kiro, Gemini CLI, VS Code Copilot, Codex), use the CLI to set up the MCP connection automatically. The reference below is for building your own MCP client or wiring up an agent the CLI doesn’t auto-configure yet.

Endpoint

The endpoint serves a session-init handshake. Send POST /mcp with an MCP initialize JSON-RPC request and the dual Accept header; the server responds 200 with an mcp-session-id you include on subsequent requests.

Quick connection — your own MCP client

# 1. Get a PAT
#    https://app.ritualapp.cloud/settings/tokens → Create token

# 2. Initialize a session
curl -X POST https://mcp.ritualapp.cloud/mcp \
  -H "Authorization: Bearer ritual_pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "my-client", "version": "0.1.0"}
    }
  }'

Response includes an Mcp-Session-Id header (e.g. mcp-session-id: 9975a189-…). Pass that as a header on every subsequent request:

curl -X POST https://mcp.ritualapp.cloud/mcp \
  -H "Authorization: Bearer ritual_pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: 9975a189-…" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Wiring up specific clients manually

Easiest path: run ritual init and the CLI auto-detects every supported agent on your machine and registers Ritual against your freshly-minted PAT. The per-client recipes below are for when the CLI doesn’t auto-configure your client yet, or you want to wire it up by hand.

What every client needs

Three things, regardless of which client you’re configuring:

1. The URL — https://mcp.ritualapp.cloud/mcp
2. The auth header — Authorization: Bearer ritual_pat_… on every request. Get a PAT at /settings/tokens (“Create token”). Legacy rtl_… keys from earlier Ritual versions don’t authenticate here.
3. An env-var-backed config if you can — most clients support reading the bearer from an environment variable so the PAT doesn’t live in a file you might commit. The recipes below show the env-var form (RITUAL_API_KEY) wherever the client supports it.

Then each client has its own config syntax, file path, and “is it connected” check — listed in the tabs below.

claude mcp add-json --scope project ritual '{
  "type": "http",
  "url": "https://mcp.ritualapp.cloud/mcp",
  "headers": { "Authorization": "Bearer ritual_pat_YOUR_TOKEN" }
}'

{
  "mcpServers": {
    "ritual": {
      "url": "https://mcp.ritualapp.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ritual_pat_YOUR_TOKEN"
      }
    }
  }
}

codex mcp add ritual \
  --url https://mcp.ritualapp.cloud/mcp \
  --bearer-token-env-var RITUAL_API_KEY

export RITUAL_API_KEY=ritual_pat_YOUR_TOKEN

[mcp_servers.ritual]
url = "https://mcp.ritualapp.cloud/mcp"
bearer_token_env_var = "RITUAL_API_KEY"

{
  "mcpServers": {
    "ritual": {
      "url": "https://mcp.ritualapp.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ${RITUAL_API_KEY}"
      },
      "disabled": false,
      "autoApprove": [
        "find_explorations",
        "get_exploration",
        "get_recommendations",
        "get_workspace_overview",
        "query_knowledge_graph",
        "score_context_pulse"
      ]
    }
  }
}

{
  "mcpServers": {
    "ritual": {
      "serverUrl": "https://mcp.ritualapp.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ritual_pat_YOUR_TOKEN"
      }
    }
  }
}

{
  "servers": {
    "ritual": {
      "type": "http",
      "url": "https://mcp.ritualapp.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ritual_pat_YOUR_TOKEN"
      }
    }
  }
}

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.ritualapp.cloud/mcp",
      "name": "ritual",
      "authorization_token": "ritual_pat_YOUR_TOKEN"
    }
  ]
}

Tools

Tools exposed today. Tool names + arg shapes are stable; new tools are added; existing ones don’t break.

Discovery & state

Reasoning Readiness scoring

Discovery → recommendations pipeline

Build brief + KG writeback

Workspace + collaborator management

Typical client flow

For a coding-agent integration:

1. find_explorations — locate the right exploration with a natural-language query, or score_context_pulse if starting from a raw feature description.
2. get_exploration + get_recommendations — load the structured context.
3. generate_build_brief (if not already generated) — pull the implementation-ready delivery context.
4. Code the change against the brief.
5. sync_implementation — writeback what shipped as code lands. Future builds in this workspace reuse the decisions.

FAQ

Related

• CLI — auto-configures the MCP connection in supported agents
• API keys — create + rotate PATs
• Build stages — what each stage of /ritual build does
• Context Pulse — Reasoning Readiness scoring
• Model Context Protocol — protocol spec