MCP server

Connect the MCP server in the portal →

The guided connect page mints a scoped MCP access token and walks you through your client’s config.

AI Reserve also ships a hosted, remote MCP server, so the agents you just connected can operate your account — not just spend your tokens. Over one streamable-HTTP endpoint your agent gets the live model catalog with pricing, usage analytics, team and API-key management, and one-shot inference — all as the connected user, bounded by what that user’s role already allows. Any MCP client that speaks streamable HTTP with a bearer header works; Claude Code, Codex, and Cursor are spelled out below, and the raw HTTP calls are documented for everything else.

POST https://api.aireserve.com/mcp
Authorization: Bearer aireserve_mcp_…   # an MCP access token — NOT an inference key

Every capability is listed in the MCP tool reference — all 22 tools and 90+ operations an enterprise admin can call, each with a copy-paste request and the plain-English ask that makes an agent do it for you.

Credentials

MCP access tokens are minted on the portal Keys page, under Management keys: explicitly scoped, expiring (7, 30, 90, or 365 days), revocable, and shown once. Revocation applies on the token’s next request. Inference keys (aireserve_api_…) are deliberately refused at this endpoint — a leaked inference credential must never gain management powers. Scopes only ever narrow. A token can never grant its owner anything their account role does not already have:

Scope	Grants
`mcp:read`	Read-only tools: `whoami`, the model catalog, the connection guide, and every `*-query` tool your role can see
`mcp:write`	The `*-action` tools — account and team management you are already authorized for
`mcp:messages`	`send-message` — one-shot inference through the gateway, billed to your account

Export the token once and let every config below read it from the environment, so no secret lands in a file that might get committed:

export AIRESERVE_MCP_TOKEN="aireserve_mcp_…"   # ~/.zshrc or a secrets manager

Clients that speak MCP OAuth don’t need a pre-minted token. The server implements the standard discovery chain — a 401 carries a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource/mcp, and from there your client finds:

Endpoint	URL
Authorization	`https://api.aireserve.com/mcp-authorize`
Token	`https://api.aireserve.com/mcp/oauth/token`
Dynamic client registration	`https://api.aireserve.com/mcp/oauth/register`

PKCE (S256) is required and clients are public (token_endpoint_auth_methods_supported: ["none"]). Approving the consent page mints the same kind of scoped, expiring token — it just never passes through your hands. In Claude Code, /mcp → Authenticate runs this flow; claude.ai and Claude Desktop custom connectors work the same way.

Claude Code

claude mcp add --transport http aireserve https://api.aireserve.com/mcp \
  --header "Authorization: Bearer $AIRESERVE_MCP_TOKEN"

Default scope is the current project; add -s user for all your projects. For a committable project config use .mcp.json — ${AIRESERVE_MCP_TOKEN} expands from the environment:

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

Verify with claude mcp list (or /mcp in a session). Tools surface as mcp__aireserve__… — try mcp__aireserve__whoami.

Codex

codex mcp add only handles stdio servers; remote HTTP servers go in ~/.codex/config.toml, with the bearer token referenced by environment variable. The same config is honored by the Codex CLI, the IDE extension, and the ChatGPT desktop app:

[mcp_servers.aireserve]
url = "https://api.aireserve.com/mcp"
bearer_token_env_var = "AIRESERVE_MCP_TOKEN"

Codex reads the variable at launch — restart Codex after exporting it, then verify with codex mcp list.

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json (per project). Note Cursor’s env interpolation is ${env:VAR} — not Claude Code’s ${VAR}:

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

Calling the API directly

No MCP client required — the endpoint is plain JSON-RPC 2.0 over HTTPS, and single tool calls work statelessly (no initialize handshake needed). Two rules:

Send Accept: application/json, text/event-stream — the server refuses requests that don’t accept both.
The response arrives as a single SSE message event whose data: line is the JSON-RPC response. The tool’s payload is JSON, serialized into result.content[0].text, with result.isError flagging failures.

List every tool your token and role can see:

curl https://api.aireserve.com/mcp \
  -H "Authorization: Bearer $AIRESERVE_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Call one — here, whoami:

curl https://api.aireserve.com/mcp \
  -H "Authorization: Bearer $AIRESERVE_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'

event: message
data: {"result":{"content":[{"type":"text","text":"{
  \"user\": { \"email\": \"jordan@acme.com\", \"name\": \"Jordan Lee\", \"role\": \"enterprise_admin\" },
  \"organization\": { \"id\": \"9cba8ede-…\", \"name\": \"Acme\" },
  \"authority\": { \"kind\": \"admin\", \"platform\": false },
  \"scopes\": [\"mcp:read\", \"mcp:write\", \"mcp:messages\"],
  \"tokenExpiresAt\": \"2027-08-05T16:34:29.000Z\"
}"}],"isError":false},"jsonrpc":"2.0","id":1}

The tool surface is computed per request

There is no fixed tool list. On every request the server verifies your token, derives your live role, intersects it with the token’s scopes, and builds the tool set fresh — an analyst and an admin literally see different tools, and a role change or token revocation applies on the very next call.

Your role	What you see
Enterprise admin	Everything: 22 tools spanning members, teams and budgets, org API keys, analytics, model policy and routing, org settings, files, and billing — plus the personal and fixed tools
Team lead (manager of an org node)	Personal tools, plus `invite_user` and the team-scoped budget/membership actions for their own subtree
Member	The fixed tools plus `personal-query` / `personal-action` — own usage, own budget, own API keys, own default model

Super admins are deliberately de-escalated on this surface: over MCP a platform operator acts as an enterprise admin of their own organization only — never across tenants. Beyond the five fixed tools (whoami, list-models, get-model, get-connection-guide, send-message), tools come in per-domain pairs — <domain>-query for reads, <domain>-action for writes. Each takes one operation per call, wrapped as {"query": {"action": …, "input": {…}}} or {"proposal": {"action": …, "input": {…}}}. The tool reference lists every operation with a runnable request. Every action resolves to one of three response shapes. Reads and plain writes execute immediately (your MCP client’s own human-in-the-loop approves tool invocations; the server’s authorization guards enforce regardless). High-stakes and secret-revealing actions add a server-side step that no client setting can skip: 1. Executed — reads and plain writes:

{ "status": "executed", "summary": "Set default chat model to claude-sonnet-4-6", "ok": true, "message": "Default model set to claude-sonnet-4-6" }

2. Needs confirmation — irreversible or other-people-affecting actions (revoking keys, deactivating members, moving money, purging content). The first call returns the exact consent line plus a signed confirmToken binding the operation, input, and caller. Show the summary to a human; only after they approve, repeat the same call with the token attached. Tokens expire in 10 minutes, and execution re-checks the target — if the row changed since the human read the line, the call is refused instead of doing something they didn’t approve:

{
  "status": "needs_confirmation",
  "summary": "Revoke API key \"CI pipeline\" (aireserve_api_493…28e5ae)",
  "confirmNote": "Irreversible — the key stops working immediately.",
  "confirmToken": "eyJhbGciOi…",
  "message": "High-stakes action: show the user the summary and note, and only after they explicitly approve, call this tool again with the same proposal plus this confirmToken. The token expires in 10 minutes."
}

3. Portal redemption — actions that reveal a one-time secret (minting API keys, file download links). The secret never passes through the MCP connection or the model’s context. Instead the call returns a signed, user-bound portal link, valid for 15 minutes; opening it in a signed-in browser confirms the action and shows the secret exactly once. Nothing is created until the link is redeemed:

{
  "status": "portal_redemption",
  "summary": "Create API key \"CI pipeline\"",
  "url": "https://portal.aireserve.com/mcp-redeem?intent=eyJvcCI6…",
  "message": "This action reveals a one-time secret, which never passes through this connection. Give the user the link — it opens in the portal, where they confirm and see the secret once. The link expires in 15 minutes."
}

Why you can’t get an API key’s secret over the API. This is a design guarantee, not a gap: management credentials for LLM-driven channels must never let a prompt injection exfiltrate a fresh key. The redemption link is the proof the action is authorized; the signed-in human click is the only place the secret exists.

Rate limits and errors

Only tools/call messages are metered — initialize, ping, and tools/list are free protocol chatter. Limits are enforced per organization (the same request-per-minute and per-day limits as the machine API); over the limit you get 429 with a Retry-After header. Ask get-connection-guide for your organization’s effective values. Authorization failures relay a human-readable reason (invalid_token on the HTTP layer for bad credentials; in-band {"error": …} tool results for operations your role can’t perform). send-message can legitimately take a while on slow models — the endpoint allows up to 120 seconds per call.

What agents can do — and what they can’t

Everything, catalogued

The complete reference: every tool, every operation, who can call it, a copy-paste request for each, and the natural-language ask that does the same thing.

Hard limits

No secrets in responses — ever. No platform (cross-tenant) operations. No inference keys accepted. No impersonation, no file-byte uploads. Every write runs the same server-side authorization guards as the portal UI.

Getting started

Connect your tool

Models

Capabilities

Migrate

Data & privacy

Connect the MCP server in the portal →

Credentials

Claude Code

Codex

Cursor

Calling the API directly

The tool surface is computed per request

Rate limits and errors

What agents can do — and what they can’t

Everything, catalogued

Hard limits

Connect the MCP server in the portal →

​Credentials

​Or sign in with OAuth

​Claude Code

​Codex

​Cursor

​Calling the API directly

​The tool surface is computed per request

​Consent and secrets

​Rate limits and errors

​What agents can do — and what they can’t

Everything, catalogued

Hard limits

Credentials

Or sign in with OAuth

Claude Code

Codex

Cursor

Calling the API directly

The tool surface is computed per request

Consent and secrets

Rate limits and errors

What agents can do — and what they can’t