Repository Public
1# MCP connections23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45An 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.67Choose where the connection runs based on where the server is reachable:89| Connection | Where it runs | Requires an environment |10| -------------------------------------------------- | --------------------------------------- | ----------------------- |11| HTTP with `connection_origin: "service"` (default) | OpenAI | No |12| HTTP with `connection_origin: "environment"` | Your session's environment | Yes |13| stdio | A process in your session's environment | Yes |14151617181920## Connect from OpenAI2122Add an HTTP MCP server to `agent.tools`. The server must be reachable from OpenAI. This works with or without a session environment.2324For example, the OpenAI documentation MCP allows anonymous access:2526```json27{28 "type": "mcp",29 "server_label": "openai_docs",30 "transport": {31 "type": "http",32 "server_url": "https://developers.openai.com/mcp"33 },34 "connection_origin": "service",35 "required": true36}37```3839<picture>40 <source41 media="(max-width: 640px)"42 srcSet="/images/api/agents-api/remote-mcps-1-mobile.webp"43 width="680"44 height="956"45 />46 <img src="https://developers.openai.com/images/api/agents-api/remote-mcps-1.webp"47 width="1400"48 height="624"49 alt="The Agents API service connects to a remote MCP server and exchanges calls and results. An optional attached vault supplies a credential matched to the server URL."50 loading="lazy"51 />52</picture>53545556575859## Connect from your environment6061An executor MCP connects from the session's environment. Use it for servers on a private network or software installed in that environment.6263Set the session's `environment.type` to `self_hosted` or `openai_hosted`. For a self-hosted environment, [connect the executor](https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted) before the agent uses its tools.6465### Connect over HTTP6667Use HTTP for a server that is already running. Add this entry to `agent.tools`, replacing the URL with an address your environment can reach:6869```json70{71 "type": "mcp",72 "server_label": "internal_search",73 "transport": {74 "type": "http",75 "server_url": "https://mcp.internal.example.com/search"76 },77 "connection_origin": "environment",78 "required": true79}80```8182Here, a localhost URL refers to the session's environment. If you omit `connection_origin`, OpenAI makes the connection instead.83848586878889### Start a server over stdio9091Use stdio to let the executor start a server process. Install the server and its dependencies in the environment first.9293For this customer lookup example, install the MCP SDK:9495```bash96python3 -m venv /workspace/mcp-demo97/workspace/mcp-demo/bin/python -m pip install 'mcp==1.26.0'98```99100Save the server as `/workspace/lookup_mcp.py`:101102Run a customer lookup MCP server103104```python105import sys106107from mcp.server.fastmcp import FastMCP108109server = FastMCP("customer-lookup", host="127.0.0.1", port=8765, stateless_http=True)110111112@server.tool()113def get_customer(customer_id: str) -> dict:114 """Look up a customer in the example data."""115 customers = {"123": {"name": "Example Customer", "plan": "pro"}}116 return {"customer": customers.get(customer_id)}117118119if __name__ == "__main__":120 transport = sys.argv[1] if len(sys.argv) > 1 else "streamable-http"121 server.run(transport=transport)122```123124125Add the server to `agent.tools`. The `stdio` argument selects the script's transport:126127```json128{129 "type": "mcp",130 "server_label": "customer_lookup",131 "transport": {132 "type": "stdio",133 "command": "/workspace/mcp-demo/bin/python",134 "args": ["/workspace/lookup_mcp.py", "stdio"],135 "cwd": "/workspace"136 },137 "required": true138}139```140141For stdio, `command` and an absolute `cwd` are required; `args` is optional. Omit `connection_origin`.142143Send a message asking the agent to look up customer `123`. The tool returns `Example Customer` on the `pro` plan.144145For 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.146147148149150151152153154155156157158## Add authentication159160For a server that allows anonymous access, omit authentication fields and `vault_ids`. Otherwise, choose the credential source for your connection:161162- **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.163- **Reusable HTTP credentials:** Store credentials in a [vault](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults) 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.164- **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`.165166For example, an HTTP transport can include a bearer token and another header:167168```json169{170 "type": "http",171 "server_url": "https://mcp.example.com/mcp",172 "authorization": "Bearer YOUR_MCP_ACCESS_TOKEN",173 "headers": { "X-Tenant-ID": "tenant_123" }174}175```176177Use 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.178179Keep secrets out of reusable agent definitions, plugin archives, and logs. To keep credentials inaccessible to agent-generated code, use a [trusted proxy or server](https://developers.openai.com/api/docs/guides/agents-api/environments/security#broker-third-party-access) that supplies them outside the environment.180181182183184## Control tool access and startup185186Set `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.187188See the [Create session reference](https://developers.openai.com/api/reference/resources/beta/subresources/agents/subresources/sessions/methods/create) for all MCP configuration fields.189190191192193194195## Troubleshoot connections196197If a required server cannot initialize, inspect the error in `agent.session.turn.failed`. For stdio servers, also check the MCP process logs.198199- **Network access:** Check the URL and `connection_origin`. For environment connections, check that the executor is connected and its network can reach the server.200- **Credentials:** Check the token or headers. For a vault, check that the credential matches the server URL.201- **Executable and dependencies:** Check that the configured command runs inside the environment.202- **Working directory:** Use an existing absolute `cwd` for an inline stdio configuration.203204205206207## Related guides208209- [Plugins](https://developers.openai.com/api/docs/guides/agents-api/tools/plugins) package MCP configuration and skills for reuse across sessions.210- [Tool search](https://developers.openai.com/api/docs/guides/tools-tool-search#agents-api) explains automatic MCP tool discovery on supported models and providers.