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.
What a client sees
Section titled “What a client sees”- Tools are the catalog operations whose
surfacesincludemcp, plussearch(federated search across every source). Reads havemcpby default; writes do not. - Annotations come from each operation’s effect:
readOnlyHint,destructiveHint,idempotentHint. - Results have
x-aidy.redactfields removed. - Calls go to your API as the user, with an
Aidy-Assertionwhosecidis the MCP request id. Your authorization decides, exactly as for the UI.
Writes need elicitation
Section titled “Writes need elicitation”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.
Claude Code
Section titled “Claude Code”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?”).
Cursor
Section titled “Cursor”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.
Other clients
Section titled “Other clients”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.
Tokens
Section titled “Tokens”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.
OAuth discovery
Section titled “OAuth discovery”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.