MCP

Model Context Protocol

Give any MCP-capable AI tool the same Clark you talk to. Its tools call the same gateway as the REST API.

Endpoint

Endpoint	`POST /mcp` on the node, e.g. `http://127.0.0.1:8765/mcp`
Transport	Streamable HTTP with JSON responses. No server-initiated SSE stream: `GET /mcp` answers `405`.
Auth	`Authorization: Bearer <token>`, the same token as the REST API.
Protocol versions	`2025-06-18` (preferred), `2025-03-26`, `2024-11-05`
Methods	`initialize`, `ping`, `tools/list`, `tools/call`. Notifications are accepted with `202`.

Connect an AI tool

Over HTTP

For clients that support remote MCP servers with headers. Key names vary a little between clients; the server entry is a URL plus the bearer header.

{
  "mcpServers": {
    "clarkcant": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Over stdio (Claude Desktop, Cursor, …)

For clients that only speak stdio MCP, clarkcant mcp is a stdio ↔ HTTP bridge to the node's /mcp. It finds the node and token the same way the CLI does (CLARKCANT_URL, CLARKCANT_TOKEN, CLARKCANT_DATA_DIR).

{ "mcpServers": { "clarkcant": { "command": "node", "args": ["/path/to/clarkcant/apps/cli/src/main.ts", "mcp"] } } }

Tools

Tool	Arguments	What it does
`ask_clark`	`{ text, conversationId?, title? }`	Sends a message to Clark (creates a conversation when none is given) and returns Clark's reply text plus `conversationId`, `resolution`, `taskId`.
`list_conversations`	`{}`	Lists conversations.
`create_conversation`	`{ title? }`	Creates a conversation.
`read_conversation`	`{ conversationId, after? }`	The timeline as text plus structured content.
`answer_question`	`{ conversationId, questionId, text?, optionIds?, confirmed? }`	Answers a question Clark asked; `confirmed` answers a yes/no question.
`stop_reply`	`{ conversationId }`	Same as `POST /conversations/{id}/stop`: stops only that conversation's reply and keeps what it wrote.
`stop_all_work`	`{}`	Same as `POST /stop`.
`node_status`	`{}`	Same as `GET /node`.
`read_inbox`	`{}`	Same as `GET /inbox`: what is waiting on you and your notices, each with its id and the `actions` it offers now.
`act_on_notice`	`{ noticeId, action, until? }`	Same as `POST /inbox/notices/{noticeId}/actions/{action}`: marks a notice read or unread, dismisses it or undoes the dismissal within five minutes (`restore`), snoozes (`until`) or brings it back, quiets its kind or turns it back on, runs failed work again, skips a version or asks an expired question again. Your node checks the action against what the notice offers now and changes nothing when it refuses. Installing an update is not offered: it is yours to press on the notice, and your node refuses it from MCP with `PERSON_ONLY`.

No approval tool, on purpose. A person's decisions (approving a guarded action, deciding a package capability, confirming an app intent, reporting what the app did with an action the agent asked for, trusting a paired peer or issuing a grant) stay on the person's own surfaces, and MCP, the WebSocket and clarkcant api refuse them with 403 PERSON_ONLY. An AI client must not be able to approve its own action or widen its own trust. Exporting a table from the conversation as a CSV file is refused on the same relays: the file is written for the person looking at the table, not handed to a machine client. Saving a widget's file with Save As, and handing a widget a file the person chose, are refused the same way. Stop, answering a question and reading stay available; the discovery document lists these routes under personDecisions.

Raw JSON-RPC

MCP clients do this for you. To see the wire format, or to call the tools from a script:

curl -s -X POST "$CLARKCANT_URL/mcp" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize",
        "params": { "protocolVersion": "2025-06-18", "capabilities": {},
                    "clientInfo": { "name": "my-app", "version": "1.0.0" } } }'

curl -s -X POST "$CLARKCANT_URL/mcp" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

curl -s -X POST "$CLARKCANT_URL/mcp" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call",
        "params": { "name": "ask_clark",
                    "arguments": { "text": "how do I connect Cursor to you?" } } }'