Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Docs: local MCP require_approval callable form omitted from docs/mcp.md

Open Beginner friendly
  • Is something wrong?
#5,350 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
1-3 hours
Newbie friendliness
87/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
documentation

Research direction

Read the “Approval policies for local MCP servers” section in docs/mcp.md and check the callable type and constructor docstring in src/agents/mcp/server.py. Document the (run_context, agent, tool) -> bool | Awaitable[bool] form, noting that tool is the MCP SDK Tool with annotations and the documented behavior when no agent is available. Done when the supported forms and callable behavior are clear in the docs.

Written by the indexing model from the issue text.

Description

Please read this first
  • Have you read the docs? Yes — MCP docs and Human-in-the-loop
  • Have you searched for related issues? Yes. #5315 asks to expose MCP ToolAnnotations on converted FunctionTool for hooks. This issue is separate: the callable require_approval policy that already receives the original MCP Tool (including annotations) is implemented but not documented in docs/mcp.md.
Describe the docs gap

docs/mcp.md → Approval policies for local MCP servers lists these supported forms for require_approval on MCPServerStdio / MCPServerSse / MCPServerStreamableHttp:

  • "always" / "never"
  • True / False
  • per-tool map
  • grouped {always, never} object

It omits the callable form that the public type and constructor docstring already accept.

Exact doc path
  • docs/mcp.md — section starting at “Approval policies for local MCP servers” (Supported forms list)
  • Cross-link: docs/human_in_the_loop.md mentions local MCP require_approval but does not show the callable signature either
  • Examples under examples/mcp/ only demonstrate string/dict policies (get_all_mcp_tools_example, tool_filter_example)
Evidence in source (current main)

Type alias in src/agents/mcp/server.py:

LocalMCPApprovalCallable = Callable[
    [RunContextWrapper[Any], "AgentBase", MCPTool],
    MaybeAwaitable[bool],
]

Constructor docstring on MCPServer:

Accepts "always"/"never", a dict of tool names to those values, a boolean, an object with always/never tool lists … or a sync/async callable that receives (run_context, agent, tool) and returns whether the tool call needs approval.

_normalize_needs_approval accepts callables, and _get_needs_approval_for_tool invokes policy(run_context, agent, tool) with the original MCP Tool — so callers can read tool.annotations (e.g. destructiveHint / readOnlyHint) without a parallel list_tools() cache.

Minimal illustration of the undocumented form
from mcp.types import Tool
from agents.mcp import MCPServerStreamableHttp

def approve_destructive(run_context, agent, tool: Tool) -> bool:
    hints = tool.annotations
    # Require HITL when the server marks the tool destructive (or omits read-only).
    if hints and hints.read_only_hint:
        return False
    return bool(hints is None or hints.destructive_hint is not False)

server = MCPServerStreamableHttp(
    name="crm",
    params={"url": "http://localhost:8000/mcp"},
    require_approval=approve_destructive,  # valid API; missing from docs/mcp.md Supported forms
)
Expected docs change
  1. Add the callable form to the Supported forms list in docs/mcp.md, with the signature (run_context, agent, tool) -> bool | Awaitable[bool] and a note that tool is the MCP SDK Tool (annotations available).
  2. Optionally add a short example next to the existing dict example, and/or one line in docs/human_in_the_loop.md pointing at it.
  3. Note the fail-closed behavior when a callable policy is used without an agent (documented in _get_needs_approval_for_tool).

Happy to refine wording if maintainers prefer a different example shape. Because this repo accepts issues (not external PRs) for docs, filing here rather than opening a PR.

Dominant language
Python
Stars
29.9k
Forks
4.8k
Avg merge
1d 3m
Merged PRs (30d)
213

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from openai/openai-agents-python

All issues in openai/openai-agents-python

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.