MCP

The server, and how to pin it

A read-only MCP server is published on the Developers page as tavonel-mcp.mjs, pinned by sha256 in the channel manifest. It speaks JSON-RPC over stdio with no dependency and no build step, so it can be read before it is pointed at anything. Set TAVONEL_API_KEY and register it; TAVONEL_BASE_URL defaults to https://tavonel.com. Run node tavonel-mcp.mjs --doctor first: it checks the key, the channel pin and one real read, so a failure names which of the three is wrong instead of surfacing as a silent agent.

Installing it

Note There is no npm or PyPI package yet. npx @tavonel/mcp does not resolve, and neither does pip install tavonel: npm and PyPI publishing is pending and needs registry credentials nobody has issued. Install it the way this page describes — download tavonel-mcp.mjs, check it against the digest in /developer/channel.json, and point your client at the absolute path. That path is the audited one and stays supported after a package exists.

Registering it with a client

The config below is the same object every stdio MCP client accepts, under its own path. Claude Desktop reads %APPDATA%\Claude\claude_desktop_config.json on Windows and ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, and reads it at launch — restart after editing. Claude Code reads .mcp.json at the root of the project you open. The Integration recipes page carries the same block with the platform notes.

{
  "mcpServers": {
    "tavonel": {
      "command": "node",
      "args": ["/absolute/path/to/tavonel-mcp.mjs"],
      "env": {
        "TAVONEL_API_KEY": "tvnl_live_...",
        "TAVONEL_BASE_URL": "https://tavonel.com"
      }
    }
  }
}

Note The key lives in the client's env block or its secret facility, never in args — arguments show up in process listings. Give it a key scoped to reads and nothing else.

The tools it exposes

The tools it deliberately does not offer

Note There is no write tool and there is no activation tool. Activation is the moment a candidate becomes the World an organisation answers from, and it stays with a person in a browser; the server refuses to start if a tool that writes is ever added to it.

Note list_worlds lists only active Worlds, over GET /v1/collections. Candidates are excluded: a discovery list mixing accepted and unaccepted output would present both as organizational truth.

Note download_package returns a descriptor rather than the archive: the URL, the size, the signed manifest digest and the signing key id. The bytes are fetched over HTTP with the same key and checked with the verifier on the CLI page.

Remote MCP endpoint

Note Not available on this site yet. Every URL in this subsection answers 404 here. Connect through the stdio server above.

Note Who can connect. A member of a workspace on a paid plan. A free evaluation connects only where trial AI access is on, with one live key or connection at a time and the trial's daily query bound, and is otherwise refused with 402 TRIAL_FEATURE_NOT_INCLUDED. While access is opening in stages, a workspace that is not yet admitted is refused with 403 REMOTE_MCP_COHORT_EXCLUDED. If the access settings cannot be read, the endpoint admits nobody and answers 503 REMOTE_MCP_COHORT_CONFIG_INVALID.

With the switch on, the same nine read-only tools are served over MCP Streamable HTTP, protocol revision 2025-06-18, at /api/mcp — for clients that connect by URL instead of launching a local process, such as ChatGPT connectors and other web agents. The tool table is the stdio server's own file, so the two cannot list different tools, and neither has a write tool. initialize and tools/list answer without a token; every tools/call needs one.

Note Only the JSON response form of Streamable HTTP is served: each POST carries one JSON-RPC message and gets one JSON body back. There is no SSE stream (GET /api/mcp answers 405) and no Mcp-Session-Id, both of which the transport allows a server to omit. A client that insists on either will not connect.

Connecting Claude, ChatGPT or a web agent

Note These steps follow each vendor's documentation and the handshake the endpoint produces with a scripted client. Neither Claude nor ChatGPT has been connected to it yet, so the first request is the test. Both connect from the vendor's cloud and need the public https URL; neither can reach a server on your own machine without a tunnel.

1. Claude (claude.ai or Claude Desktop): Settings › Connectors › Add custom connector, name TAVONEL, URL https://tavonel.com/api/mcp, then Connect.
2. ChatGPT: Settings › Apps & Connectors › Advanced settings › Developer mode on, then create a connector with the URL https://tavonel.com/api/mcp and OAuth authentication. ChatGPT's deep research and company knowledge modes expect tools named search and fetch, which this server does not offer; whether Developer mode accepts the nine tools as they are has not been checked against ChatGPT itself.
3. Any other client: add a custom remote MCP server with the URL https://tavonel.com/api/mcp and choose OAuth as its authentication.
4. A client that implements MCP authorization is expected to find the rest itself; no real client has been connected yet. A tool call without a token answers 401 with a pointer to /.well-known/oauth-protected-resource/api/mcp, which names TAVONEL as the authorization server; /.well-known/oauth-authorization-server lists its endpoints.
5. The client registers itself and opens TAVONEL's consent page in your browser. Sign in, check the client's name and the address the token is sent to, and allow read-only access.
6. The client receives an access token and lists the tools. Ask it to run list_worlds first, then search_world or ask_world with a collection id from that list.

Claude Code and Cursor

Claude Code and Cursor take the URL directly. Use OAuth, or skip it and send an API key in the Authorization header. A key for this endpoint must hold only the five read scopes: documents:read, collections:read, worlds:read, ask:read and collections:download. Under Workspace › Developers, choose Use MCP read-only scopes before you create it, because a key with any other scope is refused at /api/mcp with 401. Keep the key in the environment variable TAVONEL_API_KEY and let the client expand it, so it never sits in a file you commit. Claude Desktop connects to a URL only through Settings › Connectors, with OAuth, as in the steps above.

{
  "mcpServers": {
    "tavonel": {
      "type": "http",
      "url": "https://tavonel.com/api/mcp",
      "headers": { "Authorization": "Bearer ${TAVONEL_API_KEY}" }
    }
  }
}

claude mcp add --transport http tavonel https://tavonel.com/api/mcp
# then run /mcp inside Claude Code and choose tavonel to sign in

{
  "mcpServers": {
    "tavonel": {
      "url": "https://tavonel.com/api/mcp",
      "headers": { "Authorization": "Bearer ${env:TAVONEL_API_KEY}" }
    }
  }
}

The OAuth flow

Note The access token is a developer API key minted for the connection, in its own form (tvnl_mcp_…): it works through /api/mcp only, and the REST API refuses it with 401 API_KEY_AUDIENCE_INVALID. It is listed under Workspace › Developers with the client's name, apart from the keys you make by hand, and can be revoked there. Reconnecting the same client replaces its earlier key. The remote endpoint refuses any key that holds a scope outside the five read scopes. Rate limits and tenant scoping are the API's own, per key and per scope.

Verifying an answer

Where signed answer receipts are on, an ask_world or POST /collections/{id}/ask answer carries signedReceipt: an Ed25519 signature, under its own scope tavonel.signed_answer_receipt.v1, over the collection, the World state, the manifest digest, the sha256 of the question (never its text), the status, the cited evidence ids and the answer's output digest. Save the whole answer as JSON, fetch the trust store from /api/export/trust, and run node tavonel-verify-answer.mjs --receipt answer.json --trust-store trust.json, adding --question-file question.txt to check the question too. It recomputes the output digest from the answer text and citations, so an answer edited after signing fails. The trust store is required, since it is where a revoked key is named; --trusted-fingerprint sha256:… may be added as a pin. A receipt stays valid if its key was valid when it signed: a key that later expired or was retired still verifies its earlier receipts, a revoked key verifies none, and a signing time in the future or a payload time that is not the signing time is refused. An answer that cannot be signed while receipts are on is withheld with 503 ANSWER_SIGNING_UNAVAILABLE, never sent unsigned.