MCP
The same API key, exposed to an AI agent as one typed tool per allowed method.
Xuda runs a Model Context Protocol server at /mcp, next to /cpi. Connect an MCP-aware agent to
it, by signing in or with an API key, and every method that key is allowed to call shows up as a
typed tool, no separate integration for AI agents to write.
Connecting
There are two ways in, and both end at the same place: an API key's rights.
Sign in (Claude connectors and other OAuth clients)
Add https://xuda.ai/mcp as a custom connector in Claude (Settings, Connectors, Add
custom connector), leave the OAuth client ID and secret empty, and press Connect. Claude opens
Xuda: sign in if you are not already, and a window in the dashboard asks which of your API keys the
connection acts as; pick one and press Connect. Claude on the web, Desktop, mobile and Cowork
share that connection, and any other Claude account adds it the same way. The dashboard's
Developers, MCP tab shows the address to paste, these steps and everything below.
Claude Code signs in the same way when you add the server without a header, then run /mcp and
choose Authenticate:
The connection never has rights of its own. Every tool call runs as the key you picked, so the key's access mode, its allowlist and its revoke are the connection's too: revoke the key under Developers, API keys and the connection stops, and the next sign in asks for another key. The page lists only your own active keys; with none, create one first.
For client developers, the server follows the MCP authorization spec:
A call to /mcp without a usable token answers 401 with WWW-Authenticate: Bearer resource_metadata="...", which is how a client finds the rest. Access tokens last an hour; refresh
tokens last 90 days and are replaced on every use. A loopback redirect URI (http://localhost or
http://127.0.0.1) matches on any port.
An API key in a header
The key goes in an Authorization: Bearer header, the same key you would use as api_key on
/cpi. There is no separate MCP credential. A request with no Authorization header, or a key
that does not resolve to an active xuda_api_keys document, is refused with 401 before any tool
is registered.
Sessions
The transport is streamable HTTP: the first request is an MCP initialize call, which opens a
session and returns an mcp-session-id header; every following request on that connection carries
the same header and the same credential. A session closes after 10 minutes without a request. A
request on a session that has closed answers 404, and an MCP client then starts a new session on
its own.
What becomes a tool
Tools are registered at the start of the session from the same access mode the key already has:
- Full access: every method in the catalog that is not
privateregisters as a tool, resolved at connect time, so a method added after the key was created is available with no change to the key itself. - Custom access: only the methods on the key's allowlist register.
A running session keeps up with its key: it looks at the key every minute, and at the modules and
plugins behind it every five, and when the set of tools has moved it sends
notifications/tools/list_changed. A client that listens (Claude does) reads the new list without
reconnecting, so a method you allow on the key reaches an agent that is already connected.
Each tool keeps the method's own shape: the tool name is the method name (get_account_projects,
dbs_read, ...), its title is the method name in Title Case, its description is the method's own
description, and its input schema is built field by field from the method's fields, mandatory
fields stay required, everything else is optional. A field with no recognized type still becomes a
permissive tool argument rather than breaking the whole session, so one oddly specified method
never takes the rest of the catalog down with it.
A key scoped to a Full Stack VPS also exposes that box's installed plugin tools alongside the ecosystem methods above, so an agent can reach both the platform and whatever the developer built on the box in one session. See Full Stack VPS.
Calling a tool
An agent calls a tool with the same arguments the method's fields describe. Xuda answers by
calling the method internally, the same way /cpi/<method> would, and hands the tool the method's
{code, data} envelope back as text. A failed call still returns normally at the MCP layer, code
-1 and up shows in the tool result exactly as it would from a plain REST call, so an agent reads
it the same way your own error handling would. See Errors.
A request that fails before any tool runs, a missing or refused credential (401), a session
that has closed (404, code -32001), a malformed MCP message, comes back as a JSON-RPC error
instead of a tool result: