Connect an MCP server

MCP is the standard way to hand an agent a set of tools that live somewhere else - your CRM, an internal service, a vendor's API, or a small server you wrote this afternoon. If a system already speaks MCP, connecting it is configuration rather than code.

This guide configures AXL as an MCP client. To go the other direction and expose an AXL agent to other MCP clients, see Connect an MCP client.

Configure a server

Add mcp.toml beside the agent's agent.toml. A local process over stdio:

[servers.files]
transport = "stdio"
command = "my-mcp-server"
args = ["--root", "/data"]
env = { API_TOKEN = "${MCP_API_TOKEN}" }

A remote server over HTTP with a shared bearer token:

[servers.crm]
transport = "http"
url = "https://mcp.example.com/mcp"
auth = { bearer = { token = "${CRM_TOKEN}" } }

Tools arrive namespaced as mcp__<server>__<tool>, so two servers can both expose a search without colliding. Use ${VAR} expansion for secrets rather than writing them into the file.

AXL negotiates the protocol lifecycle on its own - modern where the server supports it, legacy otherwise - and a per-server lifecycle key in mcp.toml pins either shape. See the MCP reference.

Shared or per-user credentials

The auth block above gives every user of the agent the same access - fine for a public data source, wrong for anything permissioned. When the downstream system should see the signed-in user's permissions instead, configure an obo block:

[servers.internal]
transport = "http"
url = "https://internal.example.com/mcp"
obo = { scope = "internal-api", description = "Use the internal API as the signed-in user" }

obo and auth are mutually exclusive - a server uses one or the other. See Reach services as the user for the identity-provider side.

Large catalogs

Some MCP servers expose hundreds of tools, and putting every schema in the prompt is expensive. Defer them behind tool search:

deferred_loading_threshold = 10000

Above that token threshold, schemas load on demand instead of up front.

When a server asks you a question

A server tool can pause mid-call with a question - a missing parameter, a confirmation. The question renders as a card the user answers, and the call resumes with the answer. This happens in interactive runs only; a headless run declines on the user's behalf. See the MCP reference for the mechanics.

Next

• Reach services as the user - OBO and token exchange.
• Render interactive MCP Apps - when a tool result should be a UI.
• Connect an MCP client - the other direction.
• MCP reference - transports, auth, and optional fields.