MCP

Model Context Protocol

Cho bất kỳ công cụ AI nào hỗ trợ MCP dùng chính Clark mà bạn đang trò chuyện. Các tool của nó gọi tới cùng gateway với REST API.

Endpoint

Endpoint	`POST /mcp` trên node, ví dụ `http://127.0.0.1:8765/mcp`
Transport	Streamable HTTP, response dạng JSON. Không có luồng SSE do server khởi tạo: `GET /mcp` trả `405`.
Xác thực	`Authorization: Bearer <token>`, cùng token với REST API.
Phiên bản giao thức	`2025-06-18` (ưu tiên), `2025-03-26`, `2024-11-05`
Method	`initialize`, `ping`, `tools/list`, `tools/call`. Notification được nhận với `202`.

Kết nối một công cụ AI

Qua HTTP

Dành cho client hỗ trợ MCP server từ xa có header. Tên khoá hơi khác nhau giữa các client; về cơ bản là một URL cộng với bearer header.

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

Qua stdio (Claude Desktop, Cursor, …)

Với client chỉ nói stdio MCP, clarkcant mcp là cầu nối stdio ↔ HTTP tới /mcp của node. Nó tìm node và token giống hệt CLI (CLARKCANT_URL, CLARKCANT_TOKEN, CLARKCANT_DATA_DIR).

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

Các tool

Tool	Tham số	Chức năng
`ask_clark`	`{ text, conversationId?, title? }`	Gửi tin nhắn cho Clark (tạo cuộc trò chuyện nếu chưa có) và trả về câu trả lời của Clark cùng `conversationId`, `resolution`, `taskId`.
`list_conversations`	`{}`	Liệt kê cuộc trò chuyện.
`create_conversation`	`{ title? }`	Tạo cuộc trò chuyện.
`read_conversation`	`{ conversationId, after? }`	Timeline dạng văn bản kèm nội dung có cấu trúc.
`answer_question`	`{ conversationId, questionId, text?, optionIds?, confirmed? }`	Trả lời câu hỏi mà Clark đặt ra; `confirmed` dùng cho câu hỏi có/không.
`stop_reply`	`{ conversationId }`	Giống `POST /conversations/{id}/stop`: chỉ dừng câu trả lời của cuộc trò chuyện đó và giữ lại phần đã viết.
`stop_all_work`	`{}`	Giống `POST /stop`.
`node_status`	`{}`	Giống `GET /node`.
`read_inbox`	`{}`	Giống `GET /inbox`: những gì đang chờ bạn và các thông báo của bạn, mỗi thông báo kèm id và các `actions` nó đưa ra lúc này.
`act_on_notice`	`{ noticeId, action, until? }`	Giống `POST /inbox/notices/{noticeId}/actions/{action}`: đánh dấu thông báo đã đọc hoặc chưa đọc, bỏ nó hoặc hoàn tác việc bỏ trong năm phút (`restore`), hoãn (`until`) hoặc đưa nó trở lại, tắt báo loại của nó hoặc báo lại, chạy lại việc bị lỗi, bỏ qua một phiên bản hoặc hỏi lại câu hỏi đã hết hạn. Node đối chiếu thao tác với những gì thông báo đưa ra lúc này và không đổi gì khi từ chối. Cài bản cập nhật không có ở đây: đó là việc của bạn, bấm trên chính thông báo, và node từ chối nó từ MCP với `PERSON_ONLY`.

Cố ý không có tool phê duyệt. Các quyết định của con người (phê duyệt hành động cần kiểm soát, quyết định năng lực của package, xác nhận ý định với ứng dụng, báo cáo ứng dụng đã làm gì với một hành động agent yêu cầu, tin cậy một peer đã ghép cặp hoặc cấp quyền) nằm trên giao diện của chính người dùng; MCP, WebSocket và clarkcant api từ chối chúng với 403 PERSON_ONLY. Một client AI không được tự phê duyệt hành động hay tự nới rộng quyền tin cậy của chính nó. Xuất một bảng trong cuộc trò chuyện ra file CSV cũng bị các relay đó từ chối: file được viết cho người đang xem bảng, không trao cho một client máy. Lưu tệp của một widget bằng Lưu thành, và trao cho widget một tệp người dùng đã chọn, cũng bị từ chối như vậy. Dừng, trả lời câu hỏi và đọc vẫn dùng được; tài liệu discovery liệt kê các route này dưới personDecisions.

JSON-RPC thô

MCP client làm việc này thay bạn. Để xem định dạng trên dây, hoặc gọi tool từ 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?" } } }'