Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

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

Aperta Adatta ai principianti
  • Qualcosa non va?
#5,350 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
1/5
Tempo stimato
1-3 ore
Idoneità per principianti
87/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
python
Ambito
documentation

Direzione di ricerca

Leggi la sezione “Approval policies for local MCP servers” in docs/mcp.md e controlla il tipo callable e la docstring del costruttore in src/agents/mcp/server.py. Documenta la forma (run_context, agent, tool) -> bool | Awaitable[bool] e specifica che tool è il Tool dell’MCP SDK con le annotazioni, oltre al comportamento documentato quando non è disponibile alcun agente. Il lavoro è concluso quando le forme supportate e il comportamento del callable sono chiari nella documentazione.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.

Lingua principale
Python
Stelle
29.9k
Fork
4.8k
Merge medio
22h 17m
PR unite (30g)
208

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di openai/openai-agents-python

Tutte le issue di openai/openai-agents-python

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.