MCP connections

An MCP server publishes tool definitions and runs tool calls. The Agents API discovers the tools, calls the server, and returns results to the agent. Your application does not need to handle each call.

Choose where the connection runs based on where the server is reachable:

Connect from OpenAI

Add an HTTP MCP server to agent.tools. The server must be reachable from OpenAI. This works with or without a session environment.

For example, the OpenAI documentation MCP allows anonymous access:

12345678910{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": {
    "type": "http",
    "server_url": "https://developers.openai.com/mcp"
  },
  "connection_origin": "service",
  "required": true
}

Connect from your environment

An executor MCP connects from the session’s environment. Use it for servers on a private network or software installed in that environment.

Set the session’s environment.type to self_hosted or openai_hosted. For a self-hosted environment, connect the executor before the agent uses its tools.

Connect over HTTP

Use HTTP for a server that is already running. Add this entry to agent.tools, replacing the URL with an address your environment can reach:

12345678910{
  "type": "mcp",
  "server_label": "internal_search",
  "transport": {
    "type": "http",
    "server_url": "https://mcp.internal.example.com/search"
  },
  "connection_origin": "environment",
  "required": true
}

Here, a localhost URL refers to the session’s environment. If you omit connection_origin, OpenAI makes the connection instead.

Start a server over stdio

Use stdio to let the executor start a server process. Install the server and its dependencies in the environment first.

For this customer lookup example, install the MCP SDK:

python3 -m venv /workspace/mcp-demo
/workspace/mcp-demo/bin/python -m pip install 'mcp==1.26.0'

Save the server as /workspace/lookup_mcp.py:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import sys

from mcp.server.fastmcp import FastMCP

server = FastMCP("customer-lookup", host="127.0.0.1", port=8765, stateless_http=True)


@server.tool()
def get_customer(customer_id: str) -> dict:
    """Look up a customer in the example data."""
    customers = {"123": {"name": "Example Customer", "plan": "pro"}}
    return {"customer": customers.get(customer_id)}


if __name__ == "__main__":
    transport = sys.argv[1] if len(sys.argv) > 1 else "streamable-http"
    server.run(transport=transport)

Add the server to agent.tools. The stdio argument selects the script’s transport:

1234567891011{
  "type": "mcp",
  "server_label": "customer_lookup",
  "transport": {
    "type": "stdio",
    "command": "/workspace/mcp-demo/bin/python",
    "args": ["/workspace/lookup_mcp.py", "stdio"],
    "cwd": "/workspace"
  },
  "required": true
}

For stdio, command and an absolute cwd are required; args is optional. Omit connection_origin.

Send a message asking the agent to look up customer 123. The tool returns Example Customer on the pro plan.

For OpenAI-hosted stdio MCPs, omit the network policy or set it to enabled. The disabled and restricted network policies are not supported for these connections.

Add authentication

For a server that allows anonymous access, omit authentication fields and vault_ids. Otherwise, choose the credential source for your connection:

• HTTP credentials for one session: Set transport.authorization or transport.headers when creating the session. The Agents API encrypts these values and omits them from the returned session resource.
• Reusable HTTP credentials: Store credentials in a vault and attach it through vault_ids. Vaults apply only to connections from OpenAI. Credentials match the server URL; use credential_id to select one when several match.
• Stdio credentials: Supply values in the environment and list their names in transport.env_vars. These values can be read by code running in the environment. Self-hosted sessions do not accept inline values in transport.env.

For example, an HTTP transport can include a bearer token and another header:

123456{
  "type": "http",
  "server_url": "https://mcp.example.com/mcp",
  "authorization": "Bearer YOUR_MCP_ACCESS_TOKEN",
  "headers": { "X-Tenant-ID": "tenant_123" }
}

Use one source for Authorization: inline configuration or a matching vault credential. Other headers can accompany vault authentication. Environment-origin HTTP does not use vault credentials; use inline authentication or a trusted proxy.

Keep secrets out of reusable agent definitions, plugin archives, and logs. To keep credentials inaccessible to agent-generated code, use a trusted proxy or server that supplies them outside the environment.

Control tool access and startup

Set allowed_tools to limit which tools the agent can discover and call. Set required: true to fail the turn if the server cannot initialize. Initialization is optional by default.

See the Create session reference for all MCP configuration fields.

Troubleshoot connections

If a required server cannot initialize, inspect the error in agent.session.turn.failed. For stdio servers, also check the MCP process logs.

• Network access: Check the URL and connection_origin. For environment connections, check that the executor is connected and its network can reach the server.
• Credentials: Check the token or headers. For a vault, check that the credential matches the server URL.
• Executable and dependencies: Check that the configured command runs inside the environment.
• Working directory: Use an existing absolute cwd for an inline stdio configuration.

Related guides

• Plugins package MCP configuration and skills for reuse across sessions.
• Tool search explains automatic MCP tool discovery on supported models and providers.