Authentication patterns

MCP does not mandate one authentication scheme, so real servers take credentials in different places. The examples in this section cover every shape you are likely to meet. The Agent code barely changes; what changes is where the key goes.

Shape	Server in these examples	Code
No auth	DeepWiki, GitMCP, Microsoft Learn, Context7	`mcp_url="https://..."`
Query parameter	Exa	key interpolated into the URL
Bearer header	Semgrep	`mcp_api_key="env:TOKEN"`
URL path segment	Firecrawl	key interpolated into the path
Optional Bearer	Hugging Face	`mcp_api_key=("env:TOKEN" if TOKEN else None)`
Custom header	—	`MCPConnection(api_key_header=...)`
OAuth 2.1	—	`MCPOAuthConfig(...)`
Your own `MCPDeployer` server	any agent you serve	`MCPConnection(api_key=...)`

The `env:` prefix

For MCP credentials (api_key, mcp_api_key, authorization_token, the OAuth fields, and stdio env values), "env:VAR_NAME" reads the value from the environment when the connection is made, instead of embedding it in your source. headers values are sent as written:

mcp_api_key="env:SEMGREP_APP_TOKEN"

"${VAR_NAME}" works too. Prefer either over os.getenv(...) at construction time: the literal never enters the agent object, so it cannot leak through a serialized config or a printed repr.

No authentication

from swarms import Agent

agent = Agent(
    agent_name="MCP-Agent",
    model_name="claude-sonnet-5",
    mcp_url="https://mcp.deepwiki.com/mcp",
    max_loops=1,
)

Bearer token

The most common shape. The token is sent as Authorization: Bearer <key>.

agent = Agent(
    agent_name="MCP-Agent",
    model_name="gpt-5.4",
    mcp_url="https://mcp.semgrep.ai/mcp",
    mcp_api_key="env:SEMGREP_APP_TOKEN",
    max_loops=2,
)

mcp_api_key applies to every server that does not define its own credential, which makes it the right choice for a single server and the wrong one when servers need different keys.

Query parameter

Some hosted servers want the key in the URL’s query string. Build the URL from the environment:

import os

agent = Agent(
    agent_name="Exa-Search-Agent",
    model_name="gpt-5.4",
    mcp_url=f"https://mcp.exa.ai/mcp?exaApiKey={os.getenv('EXA_API_KEY')}",
    max_loops=2,
)

URL path segment

Firecrawl takes the key as part of the path:

import os

FIRECRAWL_API_KEY = os.getenv("FIRECRAWL_API_KEY")

agent = Agent(
    agent_name="Firecrawl-Analyst",
    model_name="claude-opus-5",
    mcp_url=f"https://mcp.firecrawl.dev/{FIRECRAWL_API_KEY}/v2/mcp",
    max_loops=2,
)

When the key lives in the URL — path or query string — never log the constructed URL. URLs end up in application logs, error traces, and crash reports far more readily than headers do. Check for the variable up front so a missing key fails with a clear message instead of a malformed URL.

Optional authentication

For a server that serves anonymous traffic, a missing key should lower your rate limit, not crash your program:

import os

HF_TOKEN = os.getenv("HF_TOKEN")

agent = Agent(
    agent_name="HuggingFace-Scout",
    model_name="claude-haiku-4-5",
    mcp_url="https://huggingface.co/mcp",
    mcp_api_key=("env:HF_TOKEN" if HF_TOKEN else None),
    max_loops=2,
)

Custom header

When a server wants its key in something other than Authorization, use an MCPConnection and set the header and prefix explicitly:

from swarms import Agent
from swarms.schemas.mcp_schemas import MCPConnection

agent = Agent(
    agent_name="MCP-Agent",
    model_name="gpt-5.4",
    mcp_config=MCPConnection(
        url="https://api.example.com/mcp",
        api_key="env:EXAMPLE_API_KEY",
        api_key_header="X-API-Key",
        api_key_prefix=None,      # send the raw key, with no "Bearer " prefix
    ),
)

MCPConnection is also where per-server timeouts and transports live:

MCPConnection(
    url="http://localhost:8000/mcp",
    name="local-tools",     # shown in logs and used for routing
    timeout=5,              # HTTP request timeout, seconds
    tool_timeout=120,       # how long a single tool call may run
    transport="streamable_http",   # or "sse", "stdio", "auto"
)

OAuth 2.1

For servers that speak the MCP authorization spec. The browser flow runs once and the tokens are cached under ~/.swarms/mcp_auth/, so later runs are silent:

from swarms import Agent
from swarms.schemas.mcp_schemas import MCPOAuthConfig

agent = Agent(
    agent_name="MCP-Agent",
    model_name="gpt-5.4",
    mcp_url="https://api.example.com/mcp",
    mcp_oauth=MCPOAuthConfig(scopes=["mcp:tools", "offline_access"]),
)

Headless, for servers that issue machine tokens:

mcp_oauth = MCPOAuthConfig(
    grant_type="client_credentials",
    client_id="env:MCP_CLIENT_ID",
    client_secret="env:MCP_CLIENT_SECRET",
)

And when you already hold a token from elsewhere, pass it directly with access_token= and no flow is run.

A server you deployed with MCPDeployer

An agent or swarm served with MCPDeployer accepts its key either as Authorization: Bearer <key>, which is what MCPConnection sends by default, or in an x-api-key header:

from swarms import Agent
from swarms.schemas.mcp_schemas import MCPConnection

agent = Agent(
    agent_name="Client",
    model_name="gpt-5.4",
    mcp_url=MCPConnection(
        url="http://127.0.0.1:8000/mcp",
        api_key="env:ANALYST_MCP_KEY",
    ),
    max_loops=2,
)

If the server uses a custom auth callable that reads more headers, such as a tenant id, add them with headers={"x-tenant": "acme"}. See Serve an agent over MCP for the server side.

Different credentials per server

Mix plain URLs and connection objects in the same mcp_urls list:

import os

from swarms import Agent
from swarms.schemas.mcp_schemas import MCPConnection

agent = Agent(
    agent_name="Research-Agent",
    model_name="claude-sonnet-5",
    mcp_urls=[
        "https://mcp.deepwiki.com/mcp",                                  # open
        f"https://mcp.exa.ai/mcp?exaApiKey={os.getenv('EXA_API_KEY')}",  # key in URL
        MCPConnection(                                                    # key in header
            url="https://mcp.semgrep.ai/mcp",
            api_key="env:SEMGREP_APP_TOKEN",
            name="semgrep",
        ),
    ],
    max_loops=3,
)

Troubleshooting

401 Unauthorized

Confirm the variable is exported in the shell that runs the script (echo $TOKEN), and that you used the shape the server expects — a Bearer token sent as a query parameter fails exactly like a missing one. Note that servers change their requirements: Semgrep once accepted anonymous traffic and no longer does. With mcp 2.x the client does not see the status code: a rejected credential surfaces as Server returned an error response.

The key looks right but the URL is malformed

An unset environment variable interpolates as the string None. Check for the variable and exit with a clear message before constructing the URL.

OAuth opens a browser on a server with no display

Set open_browser=False on MCPOAuthConfig — the authorization URL is logged instead — or use the client_credentials grant.

Sources: deepwiki_minimal.py, mcp_connection_object.py, and client/05_auth_and_config.py

Index

Basic Examples

Model Providers

Single Agent

Tree of Thoughts

Multi-Agent Examples

Auto Agent Builder

Scheduled Agents

Applications

Research

Technical Analysis

Use Cases

Finance

Voice Agents

Integrations

MCP Tool Integrations

Deployment

CLI

Authentication patterns

The `env:` prefix

No authentication

Bearer token

Query parameter

URL path segment

Optional authentication

Custom header

OAuth 2.1

A server you deployed with MCPDeployer

Different credentials per server

Troubleshooting

See also

​The env: prefix

​No authentication

​Bearer token

​Query parameter

​URL path segment

​Optional authentication

​Custom header

​OAuth 2.1

​A server you deployed with MCPDeployer

​Different credentials per server

​Troubleshooting

​See also

The `env:` prefix

No authentication

Bearer token

Query parameter

URL path segment

Optional authentication

Custom header

OAuth 2.1

A server you deployed with MCPDeployer

Different credentials per server

Troubleshooting

See also