Hosted MCP Server Skill

This skill helps create and configure hosted Model Context Protocol (MCP) server connections for OpenAI Agents SDK.

Purpose

• Create HostedMCPTool configurations
• Configure server parameters and authentication
• Set up approval flows for sensitive operations
• Connect to publicly accessible MCP servers

HostedMCPTool Properties

• tool_config (Mcp object/dict): The MCP tool config, which includes the server URL and other settings
• on_approval_request (function): An optional function that will be called if approval is requested for an MCP tool. The function takes an MCPToolApprovalRequest object as input and returns a dictionary with:
  • approve (bool): Whether to approve the tool call
  • reason (string, optional): An optional reason, if rejected
  • The function can be synchronous or asynchronous (return type can be awaitable)

Mcp Object Properties (for tool_config)

• type (string, required): The type of the MCP tool. Always "mcp"
• server_label (string, required): A label for this MCP server, used to identify it in tool calls
• server_url (string): The URL for the MCP server (one of server_url or connector_id must be provided)
• server_description (string): Optional description of the MCP server, used to provide more context
• connector_id (string): Identifier for service connectors (one of server_url or connector_id must be provided)
• authorization (string): OAuth access token that can be used with a remote MCP server
• headers (dict): Optional HTTP headers to send to the MCP server (for authentication or other purposes)
• allowed_tools (McpAllowedTools): List of allowed tool names or a filter object
• require_approval (McpRequireApproval): Specify which of the MCP server's tools require approval

MCPToolApprovalRequest Properties

• ctx_wrapper (RunContextWrapper): The run context
• data (McpApprovalRequest): The data from the MCP tool approval request

Connector IDs Supported

• connector_dropbox
• connector_gmail
• connector_googlecalendar
• connector_googledrive
• connector_microsoftteams
• connector_outlookcalendar
• connector_outlookemail
• connector_sharepoint

Approval Options

• "always": Always require approval
• "never": Never require approval
• Object mapping: Specific approval policies per tool

Usage Context

Use this skill when:

• Connecting to publicly accessible MCP servers
• Using OpenAI's infrastructure for tool execution
• Working with service connectors
• Needing hosted tool execution without local callbacks

Basic Example

import asyncio

from agents import Agent, HostedMCPTool, Runner

async def main() -> None:
    agent = Agent(
        name="Assistant",
        tools=[
            HostedMCPTool(
                tool_config={
                    "type": "mcp",
                    "server_label": "gitmcp",
                    "server_url": "https://gitmcp.io/openai/codex",
                    "require_approval": "never",
                }
            )
        ],
    )

    result = await Runner.run(agent, "Which language is this repository written in?")
    print(result.final_output)

asyncio.run(main())

Streaming Example

result = Runner.run_streamed(agent, "Summarise this repository's top languages")
async for event in result.stream_events():
    if event.type == "run_item_stream_event":
        print(f"Received: {event.item}")
print(result.final_output)

Approval Flow Example

Use when servers can perform sensitive operations that require human or programmatic approval before execution. Configure require_approval with policies ("always", "never") or a dict mapping tool names to policies.

from agents import Agent, HostedMCPTool, MCPToolApprovalFunctionResult, MCPToolApprovalRequest

SAFE_TOOLS = {"read_project_metadata"}

def approve_tool(request: MCPToolApprovalRequest) -> MCPToolApprovalFunctionResult:
    if request.data.name in SAFE_TOOLS:
        return {"approve": True}
    return {"approve": False, "reason": "Escalate to a human reviewer"}

agent = Agent(
    name="Assistant",
    tools=[
        HostedMCPTool(
            tool_config={
                "type": "mcp",
                "server_label": "gitmcp",
                "server_url": "https://gitmcp.io/openai/codex",
                "require_approval": "always",
            },
            on_approval_request=approve_tool,
        )
    ],
)

Connector-Backed Example

Use for OpenAI connectors instead of specifying a server_url. The Responses API handles authentication and exposes the connector's tools.

import os

HostedMCPTool(
    tool_config={
        "type": "mcp",
        "server_label": "google_calendar",
        "connector_id": "connector_googlecalendar",
        "authorization": os.environ["GOOGLE_CALENDAR_AUTHORIZATION"],
        "require_approval": "never",
    }
)