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 messages as text, plus structuredContent: { cursor, hasNewer, messages }. Without after, the newest page. See below. |
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. Filing a product report on GitHub is refused the same way: only the person's own Create issue press files one. Storing or removing a stored credential (POST /credentials, DELETE /credentials/{name}) is refused too: a key decides whose account the node acts on, so the person enters or removes it in Settings; removing one also forgets the description stored beside it. A refusal answers { "code": "PERSON_ONLY", "surface", "message" }: surface is mcp, relay or cli-api, and the message names that surface, the refused method and path, and why. Stop, answering a question and reading stay available; the discovery document lists these routes under personDecisions.
Reading a conversation
read_conversation without after reads the newest page (window=latest), so a question Clark is waiting on is in it however long the conversation is. Its structuredContent.cursor is the page's last message sequence: pass it back as after to read only the messages written since. It is not the timeline's event cursor, and it never passes the newest message, so a stale or guessed after comes back as the newest message's sequence and the next read recovers. hasNewer says more messages are left after this page; read again with the new cursor until no messages come back. An empty read says No messages after N. See reading a long conversation.
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?" } } }'