Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/openai/openai-cookbook/llms.txt

Use this file to discover all available pages before exploring further.

Model Context Protocol (MCP) is an open standard for connecting language models to external tools and data sources through a unified interface. Instead of writing a custom function for every external service and routing each call through your backend, you point the model at an MCP server and it handles tool discovery, invocation, and response handling directly. The result is less infrastructure to maintain, lower latency, and a consistent pattern regardless of which services you connect to.

​
Why MCP matters

Traditional function calling works well for simple cases, but it introduces friction at scale. Every external API requires a wrapper function, a relay server to forward calls, and custom error handling. When you chain multiple services — for example, fetching data from Sentry and opening a GitHub issue in a single workflow — you end up with glue code that is hard to maintain and easy to break. MCP solves this by acting as a centralized tool host. The model connects directly to one or more MCP servers, imports their tool lists, and invokes tools without touching your backend. You configure the server once; the model handles the rest.

Commerce and payments

Add items to a Shopify cart, generate Stripe payment links, or query order status — all in a single conversation turn without custom wrapper functions.

Dev-ops and code quality

Ask Sentry for the latest error in a file, then open a GitHub issue with a suggested fix in the same agent run.

Messaging and notifications

Fetch morning headlines via web search and send a Twilio SMS summary — two different APIs, zero backend glue.

Databases and file systems

Query databases, read from the local file system, or interact with cloud storage using MCP servers built for those services.

​
How MCP works in the Responses API

When you add an MCP block to the tools array, the Responses API runtime:
1

Detects the transport

The runtime identifies whether the server uses streamable HTTP or the older HTTP-over-SSE protocol, and uses the appropriate transport.
2

Imports the tool list

The runtime calls tools/list on the server, passing any auth headers you provide. The results are written to an mcp_list_tools item in the model’s context. As long as this item is present, the list is not fetched again — this gives you caching at the conversation level.
3

Calls and approves tools

When the model decides to invoke a tool, it emits an mcp_tool_call item. By default, the stream pauses for your explicit approval. Once you trust a server, you can set require_approval: "never" to allow automatic execution.
4

Returns the result

The runtime executes the approved call, streams back the result, and the model decides whether to chain another tool call or return a final answer.

​
Connecting to an MCP server

The following example connects to a public MCP server that exposes documentation search for the tiktoken library. The model can query it directly without any wrapper code on your side. 
curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "tools": [
      {
        "type": "mcp",
        "server_label": "gitmcp",
        "server_url": "https://gitmcp.io/openai/tiktoken",
        "allowed_tools": ["search_tiktoken_documentation", "fetch_tiktoken_documentation"],
        "require_approval": "never"
      }
    ],
    "input": "How does tiktoken work?"
  }'
The same configuration in Python using the OpenAI SDK: 
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4.1",
    tools=[
        {
            "type": "mcp",
            "server_label": "gitmcp",
            "server_url": "https://gitmcp.io/openai/tiktoken",
            "allowed_tools": [
                "search_tiktoken_documentation",
                "fetch_tiktoken_documentation",
            ],
            "require_approval": "never",
        }
    ],
    input="How does tiktoken work?",
)

print(response.output_text)

​
Using MCP tools in the Agents SDK

The OpenAI Agents SDK supports MCP servers as first-class tool providers. You can mix MCP tools with regular Python function tools in the same agent. 
from agents import Agent, Runner
from agents.mcp import MCPServerStdio
import asyncio

async def main():
    # Connect to a local file system MCP server
    async with MCPServerStdio(
        params={
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp/workspace"],
        }
    ) as mcp_server:
        agent = Agent(
            name="FileAgent",
            instructions=(
                "You help users manage files. You can read, list, and write files "
                "in the workspace directory."
            ),
            mcp_servers=[mcp_server],
        )

        result = await Runner.run(
            agent,
            "List the files in the workspace and summarize what each one contains."
        )
        print(result.final_output)

asyncio.run(main())

​
Filtering tools to control scope

Remote MCP servers often expose many tools. Including all of them adds tokens to the context, increases latency, and can confuse the model. Use allowed_tools to limit which tools the model can see and call. 
# Only expose read-only tools — exclude write and delete operations
{
    "type": "mcp",
    "server_label": "github",
    "server_url": "https://api.githubcopilot.com/mcp/",
    "allowed_tools": [
        "list_issues",
        "get_issue",
        "search_repositories",
    ],
    "require_approval": "never"
}
Be deliberate about which tools you expose, especially those with write access, financial implications, or security sensitivity. A model that can delete records or charge payment methods should always require explicit approval.

​
Managing latency and caching

MCP tool discovery adds latency on the first call because the runtime fetches the server’s tool list. On subsequent turns, the mcp_list_tools item is already in context, so the fetch is skipped. Use previous_response_id to carry this item forward across turns. 
# First turn — tool list is fetched
response_1 = client.responses.create(
    model="gpt-4.1",
    tools=[{"type": "mcp", "server_label": "myserver", "server_url": "https://..."}],
    input="What tools are available?",
)

# Second turn — tool list is already in context, no re-fetch
response_2 = client.responses.create(
    model="gpt-4.1",
    tools=[{"type": "mcp", "server_label": "myserver", "server_url": "https://..."}],
    input="Use the search tool to find order #4421.",
    previous_response_id=response_1.id,
)
For high-traffic applications, consider using a non-reasoning model for MCP tasks unless your use case genuinely requires complex multi-step planning. Reasoning models produce significantly more output tokens (including reasoning tokens), which increases both latency and cost.

​
Common MCP integrations

CategoryExample servers
Code and documentationGitHub, GitMCP, Sentry
Commerce and paymentsShopify, Stripe
File systems and storageLocal filesystem, S3, Google Drive
DatabasesPostgreSQL, SQLite, Supabase
CommunicationTwilio, Slack, email
Search and knowledgeWeb search, Exa, Brave
The MCP ecosystem is growing rapidly. Check the MCP registry for a current list of available servers.

​
Next steps

OpenAI Agents SDK

Build agents that use MCP servers alongside Python function tools.

Function calling

Understand the underlying tool-call pattern that MCP builds on.

Build docs developers (and LLMs) love

Get started for freeTalk to us