Skip to content

MCP clients

Every aidy host serves MCP over streamable HTTP at <url>/mcp, for example https://console.example.com/mcp. A client authenticates with the user’s own credential, the same bearer token your API accepts, and sees the operations that user may use.

  • Tools are the catalog operations whose surfaces include mcp, plus search (federated search across every source). Reads have mcp by default; writes do not.
  • Annotations come from each operation’s effect: readOnlyHint, destructiveHint, idempotentHint.
  • Results have x-aidy.redact fields removed.
  • Calls go to your API as the user, with an Aidy-Assertion whose cid is the MCP request id. Your authorization decides, exactly as for the UI.

To expose a write to MCP, list the surface explicitly:

"x-aidy": {
"name": "stop_vm",
"surfaces": ["agent", "mcp", "cli"],
"confirmation": { "title": "Stop server {resource_name}?", "lookup": { "path": "/api/vm/{vm_id}", "labelPath": "name" } }
}

Before an operation that needs approval (approval: always, the default for writes) runs, aidy resolves its arguments, performs the confirmation lookup, and asks the user through an MCP elicitation with the confirmation text (“Stop server gpu-train-01?”). A client without elicitation support still sees the tool, but its call is refused with an explanation and nothing is executed. The check is in aidy’s code, so no prompt can skip it.

Terminal window
claude mcp add --transport http console https://console.example.com/mcp \
--header "Authorization: Bearer $CONSOLE_TOKEN"

console is the server’s name in Claude Code. Run claude mcp list to check that it connected, then ask Claude about your servers (“which VMs are running in cn-beijing-a?”).

Add the server to .cursor/mcp.json in the project, or ~/.cursor/mcp.json for every project:

{
"mcpServers": {
"console": {
"url": "https://console.example.com/mcp",
"headers": { "Authorization": "Bearer ${env:CONSOLE_TOKEN}" }
}
}
}

Cursor resolves ${env:NAME} in url and headers from the environment it was started in, so the token stays out of the file.

Any client that speaks MCP streamable HTTP works. It needs:

Setting Value
Transport Streamable HTTP
URL https://console.example.com/mcp
Header Authorization: Bearer <token>

Clients that only speak stdio can go through a bridge such as mcp-remote:

{
"mcpServers": {
"console": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://console.example.com/mcp", "--header", "Authorization: Bearer ${CONSOLE_TOKEN}"]
}
}
}

For scripts and terminals, the aidy CLI is an MCP client of the same endpoint.

The token is whatever your API accepts in Authorization: a personal access token, an API key, or an OAuth access token. aidy forwards it to your identity operation to learn who the user is, and to every call it makes. It is held in memory for the request and never stored. A token that expires makes calls fail until the client sends a fresh one.

Give users a page where they create a token for MCP use, ideally scoped and revocable like any other API token.

Clients that support MCP authorization can sign the user in through your OAuth server instead of a pasted token. Name the authorization server in aidy’s configuration:

createAidy({
// ...
mcp: { authorizationServers: ['https://auth.example.com'] },
});

aidy then serves protected-resource metadata at /.well-known/oauth-protected-resource/mcp:

{
"resource": "https://console.example.com/mcp",
"authorization_servers": ["https://auth.example.com"],
"bearer_methods_supported": ["header"]
}

An unauthenticated request to /mcp answers 401 with WWW-Authenticate: Bearer resource_metadata="https://console.example.com/.well-known/oauth-protected-resource/mcp", so the client can find the server, run the OAuth flow and retry with the access token. Your authorization server issues the tokens and your API validates them; aidy only forwards them.

When aidy runs behind a reverse proxy, route /.well-known/oauth-protected-resource/mcp to it along with /mcp; see Deploy.