MCP servers

Connect any MCP client to Anlyon's hosted MCP server, to one integration's own MCP server, or to the npm package over stdio or HTTP, and act for your company or for one of your users.

An agent that calls production APIs needs credentials, and a credential in an agent’s context can be leaked, misused or replayed. Anlyon’s MCP servers give the agent your actions as tools instead. The agent names an action and passes input. Anlyon adds the credential at dispatch, applies your limits, waits for a person when a policy says so, and records a receipt for the call. The agent never holds a token.

This page is the reference for every way to connect. For step-by-step setup in one client, see Claude Code, Cursor, Codex, Windsurf, ChatGPT, the OpenAI Responses API or the Claude Agent SDK.

Choose a server

All four serve the same tools and enforce the same scopes, limits and approvals. Every call goes through the Anlyon API at https://api.anlyon.com/api/v2.

Choose how to sign in

The hosted servers accept two credentials on the Authorization header. Anlyon tells them apart by shape: an Anlyon API key starts with anlyon_, and anything else is treated as an OAuth access token.

Sign in with OAuth

Point the client at https://api.anlyon.com/mcp. The server answers the first request with 401 and a WWW-Authenticate header that names its OAuth metadata (https://api.anlyon.com/.well-known/oauth-protected-resource/mcp). The client registers itself and opens a browser. Then:

1. Sign in to Anlyon, or create an account. A new account gets a workspace during sign-in.
2. If you belong to more than one workspace, choose the workspace and environment the client acts in. With one workspace, the connection uses its default environment.
3. Choose permissions. Actions is on. Approve on your behalf, Switch between your workspaces, Secrets, Budgets and Notification channels are off unless you turn them on.

To disconnect, remove the app in the console’s settings. Its next request is refused with 401.

Use an API key

Send the key as a bearer token:

Authorization: Bearer anlyon_live_...

Give the key only what the agent needs:

actions:read, actions:invoke, approvals:read and approvals:write are in the Standard preset. approvals:decide is privileged: give it to a reviewer’s key, never to the agent’s.

Who can decide an approval

• A key can never decide an approval it requested.
• A person can never decide an approval that their own agent requested: an app signed in as them, or a key they created. Not from that app, not from another app, not with another key. A teammate decides it. The one exception: when nobody else in the environment can decide approvals, the person decides it themselves, directly in the console or in Slack.
• An approval that needs N approvers counts each OAuth decision as one user and each key decision as one credential.

The workspace tools (list_workspaces, select_workspace) work only with OAuth. A key belongs to one environment and cannot switch.

Act for one of your users

When your product’s agent acts in your users’ accounts (their Gmail, their HubSpot), your server names the user and the model never does. Connect with an API key and add one header:

Authorization: Bearer anlyon_live_...
Anlyon-End-User: user_123

• The user is fixed for the whole connection. No tool has a user argument, so nothing the model writes can choose or switch it.
• Each call uses that user’s own connected account, counts toward that user’s limits, and waits for that user’s approval when a policy is decided by the end user.
• The id is 1 to 128 characters: letters, digits and . _ : @ -.
• An OAuth connection that sends the header is refused with 400 END_USER_HEADER_NOT_ALLOWED. OAuth connections act for you, with workspace connections.
• A key created with Require an end user refuses a connection without the header (400 END_USER_REQUIRED).

With the npm package over stdio, pass --end-user <id> or set ANLYON_END_USER instead. See Workspace connections and end-user connections for the model behind this, and Act for your users for a full app.

Tools

How the action_<name> tools work:

• An action defined in the console appears in the tool list within 30 seconds, with no restart. The list is cached for 30 seconds per caller.
• A gated action says so in its description: “Gated. It requires human approval, and the call parks until a human decides.”
• An action that declares an impact says what one call counts, for example “Each call counts emails toward any shared limit set for this environment”.
• A plain GET action with no adapter is marked read-only. Every other action is marked destructive, so a client that confirms destructive calls asks you first.
• A key without actions:read gets the fixed tools only.

Call an action and handle an approval

1. The agent calls an action tool:

   { "name": "action_update-ticket-priority", "arguments": { "ticketId": "T-1042", "priority": "high" } }

2. If the action needs approval, nothing is sent yet. The tool answers:

   Awaiting human approval. Call wait_for_approval with approvalId=apr_7Hc2... to block until they decide. The action runs by itself once approved.

   (invoke_action returns the same as JSON: "pendingApproval": true and "approvalId": "apr_...".)

3. The agent calls wait_for_approval with { "approvalId": "apr_7Hc2..." }. A reviewer decides in the console, in Slack, or with decide_approval from their own connection (who can decide). For an approval decided by the end user, that user decides in your app.

4. wait_for_approval returns the approval record:

   {
     "id": "apr_7Hc2...",
     "kind": "action",
     "status": "approved",
     "payload": { "invocationId": "inv_...", "actionName": "update-ticket-priority", "method": "PATCH" },
     "decidedBy": { "type": "user", "id": "...", "displayName": "Dana" },
     "requiredApprovals": 1,
     "approvedCount": 1
   }

   If it is still pending, the agent calls it again. If it is denied or expired, the request is never sent.

5. Approving runs the exact request that was reviewed. The invocation payload.invocationId names holds the outcome, the response and, for a governed action, the receipt grade. Read it in the console’s invocation log, or with GET /api/v2/actions/invocations/{id} (needs actions:read).

An action that does not need approval answers at once with its invocation: status (succeeded, failed or unknown), responseStatus, body, and for a governed action effectId and grade. unknown means the request may have reached the destination: do not call it again. See When the outcome is unknown.

One integration’s MCP server

Each integration has its own server at https://api.anlyon.com/mcp/<integration>. Use it when an agent needs one integration and should not see the rest of your workspace.

It serves:

• The integration’s actions, as action_<name> tools. These are the actions installed from that integration’s toolset, whose names start with <integration>-, for example action_github-create-issue. Connect the account and turn on its operations in the console first.
• check_approval and wait_for_approval, so the agent can follow a gated action to its decision.

Everything else stays on https://api.anlyon.com/mcp: list_actions, invoke_action, other integrations’ actions, deciding approvals and switching workspaces. An action you created yourself, or installed without the prefix, is served there too.

Sign-in, API keys, Anlyon-End-User, approvals and limits work exactly as on /mcp. An OAuth token issued for /mcp is accepted here too. An address that is not an integration answers 404 NOT_FOUND.

Run the npm package

@anlyonhq/mcp-server (Node 18 or later) serves the same tools from your own machine or host. It talks to the Anlyon API with an API key.

Over stdio

Your MCP client starts the process:

ANLYON_API_KEY=anlyon_live_... npx -y @anlyonhq/mcp-server

To act for one of your users, fix the user for the process:

ANLYON_API_KEY=anlyon_live_... npx -y @anlyonhq/mcp-server --end-user user_123

A malformed id stops the server at startup.

Over HTTP

Run the MCP server over HTTP yourself, for a client that needs a URL but cannot sign in with OAuth:

PORT=3001 npx -y @anlyonhq/mcp-server --http

It serves POST /mcp (streamable HTTP, stateless) on PORT, default 3001. GET /mcp returns the server’s name and version. It holds no key of its own: each request’s Authorization: Bearer <key> is the key the tools act with, and Anlyon-End-User on a request names the user. --end-user and ANLYON_END_USER are refused in this mode. It answers 401 without a bearer, 400 INVALID_END_USER for a malformed id, 415 without a JSON content type, and 413 for a body over 1 MB.

The hosted https://api.anlyon.com/mcp also accepts an API key, so run your own only when you need it on your network.

Environment variables

Fix a refused connection or call

connect_required and reconnect_required come back as a tool result, not an error, so the model can pass the message on:

{
  "status": "connect_required",
  "integration": "gmail",
  "connectUrl": "https://api.anlyon.com/connect/...",
  "message": "The user has not connected gmail yet, so nothing was done. Ask them to connect it, then try again."
}

The same fields are in the result’s structuredContent. connectUrl works once, for 10 minutes. It is null when the environment has no default redirect URL: create a link with endUsers.createConnectLink() instead.

Related

• Actions: define what the agent can call
• Approvals: policies, reviewers and N-of-M
• Impact limits: cap what calls can do per environment or per user
• Receipts and grades: what confirmed, acknowledged and unknown mean
• Workspace connections and end-user connections
• Vercel AI SDK: the same tools in a TypeScript app, without MCP