Skip to main content
Free academy website with paid plans.

AI agents

MCP server for AI agents

Connect Claude, Cursor or another MCP client to /api/mcp with a personal access token. The agent acts as you through three tools.

Updated

Browse the developer docs

Steps

  1. Open the AI agents (MCP) tab of the Developer console and select Create MCP token. The dialog opens with Personal access token chosen, the mcp:read scope ticked and the label AI agent filled in. In the Scopes list the MCP scopes are the ones whose names start with AI agents. Also tick mcp:write if the agent should make changes, then select Create key and copy the token from the MCP token created dialog.
  2. Under 2. Add ChessCore to your agent, copy the Endpoint, the Claude Code command, or the Claude Desktop / Cursor (mcp.json) config. The endpoint is your app address followed by /api/mcp. After you create a token on this tab, the command and config already include it.
  3. For Claude Code, run:
    Command
    claude mcp add --transport http chesscore <endpoint> --header "Authorization: Bearer <token>"
    .
  4. Clients connect over Streamable HTTP with POST only, one JSON-RPC 2.0 message per request. The server supports initialize, ping, tools/list and tools/call, and protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.
  5. The agent sees three tools: search_tools (find tools by keywords, up to 25 results), describe_tool (get one tool’s input schema) and call_tool (run a tool with arguments).
  6. For high-stakes tools, call_tool needs an idempotency_key. For write tools it is recommended. A retry with the same key returns the first result.
  7. Without MCP, you can use the same tools over REST with the same token: GET /api/v1/tools?q=<words>&limit=<n> (default 25, maximum 50), GET /api/v1/tools/{name} for the schema, and POST /api/v1/tools/{name} with the arguments as a JSON object. Write tools need an Idempotency-Key header.

Notes

  • Only personal access tokens work. An API key gets 403 with a message that starts with "MCP needs a personal access token". A token without an mcp scope gets 403 "this token is missing the mcp:read scope".
  • The agent acts as the person who created the token, with that person’s current role and permissions. If that person leaves the academy or the token is revoked, it stops working.
  • For /api/mcp, the token owner’s role must allow AI tools (the copilot:use permission). Otherwise every call gets 403 "your role is not allowed to use AI tools in this academy".
  • Access levels: mcp:read allows read tools. mcp:write adds write tools. mcp:admin adds high-stakes tools (payments, outbound sends, destructive actions), and only when the token owner is an owner or admin.
  • Calling a tool above the token’s level returns an error that names the scope needed. Without mcp:admin, high-stakes actions must be done inside ChessCore.
  • Write tools save an undo snapshot. Every tool run is recorded in the audit log.
  • Request bodies over 1 MiB are refused. Batched JSON-RPC messages are not supported.
  • GET and DELETE on /api/mcp return 405, because the server keeps no sessions.

Related guides

Still need help?

Email hello@chesscore.io. Using ChessCore day to day? Visit the Help centre.