Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đang mở Phù hợp với người mới
  • Có gì không ổn?
#5,350 1 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
1/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
87/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
python
Lĩnh vực
documentation

Hướng nghiên cứu

Đọc phần “Approval policies for local MCP servers” trong docs/mcp.md và kiểm tra kiểu callable cùng docstring của constructor trong src/agents/mcp/server.py. Ghi lại dạng (run_context, agent, tool) -> bool | Awaitable[bool], lưu ý rằng tool là Tool của MCP SDK có annotations, cùng với hành vi được mô tả khi không có agent. Hoàn tất khi các dạng được hỗ trợ và hành vi của callable được làm rõ trong tài liệu.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.

Ngôn ngữ chính
Python
Star
29.9k
Fork
4.8k
Merge trung bình
22 giờ 17 phút
Pull request đã merge (30 ngày)
208

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của openai/openai-agents-python

Tất cả issue của openai/openai-agents-python

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.