Skip to main content
This page documents how to attach one or more Model Context Protocol (MCP) servers to an agent via AgentSpec, so the agent can call the server’s tools while it runs.

What is MCP?

Model Context Protocol (MCP) is a standardized way for AI agents to interact with external data sources, tools, and services. By connecting an MCP server to an agent, it can:
  • Fetch real-time data (market data, internal APIs, databases)
  • Call tools exposed by the server
  • Access resources the server publishes
The MCP server’s tools are discovered automatically at run time and made available to the agent alongside any tools_list_dictionary function tools.
MCP servers are free to attach: there is no MCP fee, only the agent’s tokens are billed (see Billing below).

Ways to connect

AgentSpec exposes four related fields. Use the simplest one that fits:
Every server must be a publicly reachable https:// URL: the agent runs on the API’s servers, not on your machine. An http:// URL (including localhost), a stdio server (transport: "stdio" or a command), or an entry with no URL returns 422 MCP servers must be https:// URLs; stdio servers are not accepted.

1. mcp_url — a URL string or connection object

For an unauthenticated server, a plain URL string is enough:
mcp_url also accepts a full MCPConnection object when you need auth, a specific transport, or custom timeouts, instead of using mcp_config:

2. mcp_urls — multiple servers

mcp_urls is a plain JSON array; each entry is either a URL string or an MCPConnection object. Tools from every server are combined into one tool list for the agent:

3. mcp_config — a single connection with full control

Use mcp_config instead of mcp_url when you want the connection shape to be explicit (custom headers, an authorization token, a specific transport, or a timeout):

4. mcp_configs — multiple fully-configured connections

mcp_configs is a plain JSON array of MCPConnection objects (not wrapped in an outer object):

MCPConnection fields

All four fields above accept objects shaped like MCPConnection:

Transports

Set transport on the connection object:
  • auto (default) — SSE for URLs ending in /sse, streamable HTTP for any other URL.
  • streamable_http — HTTP-based MCP transport, used for most remote servers.
  • sse — Server-sent events transport.
The stdio transport, which launches a local process, is not accepted and returns 422.

Auth modes

If auth_type is not set explicitly, it’s inferred in this order:
  1. oauth — if oauth is set.
  2. api_key — else if api_key is set (sent via api_key_header/api_key_prefix).
  3. bearer — else if authorization_token is set (sent as Authorization: Bearer <token>, unless headers already defines Authorization).
  4. custom — else if headers is set (sent as-is).
  5. none — otherwise.

MCPOAuthConfig fields

Set oauth on the connection to use OAuth 2.1 instead of a static token or API key. Three flows are supported:
  1. authorization_code (default) — the interactive browser flow from the MCP authorization spec. PKCE and RFC 7591 dynamic client registration are handled automatically, so client_id is optional. Tokens are cached on disk so the browser prompt only happens once.
  2. client_credentials — a headless machine-to-machine flow. Requires client_id/client_secret. The token endpoint is discovered from the server’s /.well-known/oauth-authorization-server metadata unless token_url is given.
  3. A pre-obtained access_token — no flow is run; the token is sent directly as a bearer credential.

Credentials

Send tokens, API keys and OAuth secrets as literal values in the request. A string anywhere in an MCP entry that starts with env: or ${ (an environment variable reference such as "env:MY_VAR" or "${MY_VAR}") returns 422, because it would be read from the API server’s environment, not yours:

Billing

MCP servers add no fee. Attaching servers through mcp_url, mcp_urls, mcp_config, or mcp_configs costs nothing extra, however many MCP tools the agent calls. The request is billed only for the agent’s tokens, priced at the agent’s own model plus the 15% service fee; MCP tool calls and their results add tokens like any other part of the run. See the Pricing page to look up a model’s current price rather than hardcoding it, since provider prices change.

Complete example: quantitative agent with MCP

Agent Completions

Full AgentSpec field reference

Tools

Built-in auto_search/web_scraper tools and autonomous looper tools