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",
    }
)