What MCP contributes
An MCP server exposes tool definitions and executes calls. The Agents API discovers and invokes those tools. Your application does not implement a handler for each MCP call. MCP connects capabilities; it does not replace the model, agent harness, or your authorization policy.
Service versus environment connections
HTTP defaults to connection_origin: service, so OpenAI must reach the endpoint. Set connection_origin: environment for a server reachable from the sandbox. Stdio runs a process inside the environment and requires an absolute working directory. A localhost URL refers to the machine making the connection.
// Tool configuration inside agent.tools
{
type: "mcp",
server_label: "openai_docs",
transport: {
type: "http",
server_url: "https://developers.openai.com/mcp"
},
connection_origin: "service",
required: true
}Credentials and tool scope
Anonymous servers need no credential. For service-origin HTTP, a vault can provide reusable credentials matched to a server URL. Environment-origin HTTP does not use vault credentials. Limit allowed_tools and set required: true when a missing server should fail initialization.
Debug the connection
Check the connection origin, reachable URL, authentication, allowed tools, and network policy. For stdio, check installed dependencies and process logs. Inspect turn.failed when a required server cannot initialize. Treat returned text as untrusted input and enforce permissions in the downstream service.
Read the official reference
Check the source for current API fields, account requirements, and service limits.
OpenAI: mcp