MCP tool: call remote MCP servers from your API requests

Add an entry with type: "mcp" to the tools array of a POST /v1/responses request. Give it a server_label, which names the server in the output, and the server_url of a remote MCP server that speaks the streamable HTTP transport. An optional server_description helps the model decide when the server is useful.

When the request runs, the API fetches the server's tool list and makes those tools available to the model. If the model decides to use one, the API calls the server, passes the result back to the model, and continues until the model has an answer. The calls are made from our infrastructure in the EU.

Most servers need credentials. Pass them in headers, for example an Authorization header with a token for that service. Headers are used for the call and are not returned in the response, but use a token with the narrowest scope the task needs.

allowed_tools limits which of the server's tools the model may see, which keeps the prompt smaller and the behaviour predictable. require_approval controls whether a call needs your confirmation first: never runs calls automatically, always pauses each one, and an object with always and never lists sets it per tool. Use approval for tools that change data, such as creating tickets or sending messages.

The output array shows what happened in order. An mcp_list_tools item records the tools the server offered. Each call appears as an mcp_call item with the server_label, the tool name, the JSON arguments and the output the server returned, or an error. The final message item contains the answer, also available as output_text in the SDKs.

When approval is required, the response contains an mcp_approval_request item instead. To continue, send a new request with previous_response_id and an input item of type mcp_approval_response that references the request's id and sets approve to true or false.

If the server cannot be reached, rejects the credentials or returns an invalid tool list, the request fails with an error that names the server_label, or the mcp_call item carries the error so the model can explain it. Check that the URL is public over HTTPS and that the token is valid.

The model sees whatever the server returns, so only connect servers you trust; tool output can contain instructions that try to steer the model. Long tool lists and large results use input tokens, so filter with allowed_tools. Data sent to a third-party MCP server is processed by that service under its own terms, so check where it runs.