MCP for agents · Kanesh

By the end of this guide, your agent will be configured to read a Kanesh workspace through MCP. Each workspace has its own endpoint, and the agent sees only what the token’s owner can see.

Note: Kanesh does not run, host or bill any AI model and needs no AI API key. Codex and Claude Code use the subscription or account you already have; Kanesh only serves your data to them over MCP.

Before you start

Complete Getting started and have a workspace available.
Use an account with permission to read the collections you want to expose.
Be able to set environment variables for Kanesh and your agent.

Note: MCP tools are read-only. Creating collections or records requires the REST API, even when the token’s owner has write permission.

1. Enable MCP

Set this environment variable when starting Kanesh:

MCP_ENABLED=true

Then open Settings → AI & MCP in Studio. It shows the endpoint URL and config snippets for Codex and Claude Code.

2. Create a personal token

In Account → API tokens, create a personal token. The secret is shown once and stored only as a hash. Export it for your agent:

export KANESH_TOKEN=...

Note: Replace ... with the token secret. Keep it private; Studio shows it only once.

3. Connect Codex

Replace WORKSPACE_ID with your workspace ID, using the endpoint shown in Settings → AI & MCP. Configure Codex to use the exported KANESH_TOKEN:

[mcp_servers.kanesh]
url = "http://127.0.0.1:8080/api/v1/workspaces/WORKSPACE_ID/mcp"
bearer_token_env_var = "KANESH_TOKEN"

4. Read workspace data

Use these tools to inspect the schema and read records:

Tool	What it returns
`get_workspace_schema`	Collections and fields the token may read
`get_schema_model`	Saved lookups and managed indexes
`list_records`	A bounded page of records, with filters and sort

Agents that need to create collections or records can use the REST API with the same token; the OpenAPI export describes every endpoint.

Troubleshooting

MCP is unavailable: check that Kanesh was started with MCP_ENABLED=true and use the endpoint shown for the intended workspace.
Authentication fails: check that KANESH_TOKEN contains a personal token that has not expired or been revoked. Send only one credential source; duplicate credentials or a cookie plus a token return 401. Tokens in query parameters are not accepted.
An expected collection is missing: check the token owner’s effective access in that workspace. MCP uses the same permissions as Studio, REST and GraphQL.
The agent cannot write records: MCP tools are read-only. Use the REST API with an account that has the required write permission.