Kinoko developer portal

Kinoko is a substrate that external agents drive. There is no built-in agent: Claude, Cursor, Codex or anything that speaks MCP is the operator, and this page is what it needs to connect.

1. Get an API key

Sign in at kinoko.sh and create an organization. Under Settings → API keys, create a key. It is shown once, in the form kin.<org>.<secret>; it authenticates as exactly that organization and can be revoked from the same page.

2. Connect over MCP

The MCP endpoint is POST https://kinoko.sh/mcp (Streamable HTTP, protocol 2025-06-18). Send the key as a bearer token.

{
  "mcpServers": {
    "kinoko": {
      "url": "https://kinoko.sh/mcp",
      "headers": { "Authorization": "Bearer kin.org_xxx.yyy" }
    }
  }
}

initialize returns orientation in instructions; tools/list returns 22 tools; resources/list returns the four guides as kinoko://guide/*.

3. The loop

  1. workspace — every project and environment you can reach. Start here rather than asking for an id.
  2. symbols, search, read, deps, graph — look before writing. A patch replaces the declarations it names whole.
  3. stage_patch — Yabu source plus a patch id and a message. The verdict is promoted: true, or promoted: false with the type-error reasons. Fix and restage the same id.
  4. simulate, send, eval, store_query — prove it against the live environment.
  5. fork_env → patches → open_pr — a human reviews the proposal as a graph and approves it. There is no merge_pr tool; that asymmetry is deliberate.

REST

Every MCP tool is an HTTP route with the same bearer key. The full surface, with one operationId per route and request/response schemas, is published at /openapi.json. The shape:

routewhat
GET /api/projects · POST /api/projectsthe organization's projects
GET/POST /api/projects/{project}/envsenvironments in a project
GET /env/{env}/{op} · POST /env/{env}/{op}the REPL: symbols, read, search, deps, graph, stage_patch, simulate, send, call, store_list, …
GET/POST /api/prs · GET /api/prs/{id}/review · POST /api/prs/{id}/mergeproposals; merge is human-only
GET/POST /api/deploymentsthe serving registry
GET/POST /api/keys · POST /api/keys/{id}/revokeAPI keys (Clerk session only)

Errors are JSON: { "error": "<message>", "code": "<not_found|unauthorized|forbidden|bad_request|…>", "hint": "<what to do>" }.

Reading material