MCP tool wrapper injects parameters the action model forbids (pageId/timeout) — tools with mismatched inputSchema are unusable

Open
#6,793 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
42/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
python

Research direction

Start by tracing the MCP tool wrapper and the action model generation from the server's inputSchema; the issue does not name source files or tests. Compare the schema advertised to the model with the fields passed into validation, focusing on pageId and timeout. Done means tools that do not declare those fields pass validation and still call the MCP server.

Written by the indexing model from the issue text.

Description

priority:low

Bug summary

The SDK tool-call path for MCP tools fails validation with extra_forbidden errors for parameters the SDK itself injects, making certain MCP tools completely unusable through the session tool interface — the call never reaches the MCP server.

This is not model hallucination (unlike #5610 / #5608): the extra parameters (pageId, timeout) are added by the SDK's MCP tool wrapper, while the pydantic action model generated from the MCP server's real inputSchema uses extra="forbid". The schema advertised to the model and the validating model disagree.

Environment

Reproduction

Configure either MCP server and invoke a tool whose real inputSchema lacks the wrapper-injected parameters:

  • chrome-devtools_new_page → SDK injects pageId
  • browser_mcp_browser → caller passes timeout (also advertised)
Error validating tool 'chrome-devtools_new_page': 1 validation error for MCPChromeDevtoolsNewPageAction
pageId
  Extra inputs are not permitted [type=extra_forbidden, input_value=1, input_type=int]
    For further information visit https://errors.pydantic.dev/2.14/u/extra_forbidden

Analysis

The wrapper appears to add routing parameters (pageId) and lifecycle parameters (timeout) uniformly across an MCP server's tools, but the action model (MCPChromeDevtoolsNewPageAction, MCPBrowserMcpBrowserAction, …) is built from the server's declared inputSchema. For tools that legitimately don't accept those parameters (new_page, list_pages, the single aggregate browser tool), every call fails client-side validation.

Workaround

Calling the same MCP servers through the agent-server's raw MCP test endpoint (POST /api/mcp/test, which bypasses the wrapper) works correctly — the MCP servers themselves are fine, confirming the bug is in the SDK's tool-schema/action-model generation.

Expected behavior

The tool schema presented to the model and the validating action model should be generated from the same source (the MCP server's inputSchema). Wrapper-level routing/lifecycle parameters should be stripped before action-model validation (or handled out-of-band), so tools that don't declare them remain callable.

Related

  • #5488 (PR: drop unknown tool-call arguments) — would mask this class of error rather than fix the schema-mismatch root cause
  • #5610, #5608 — model-hallucinated extra params; same symptom (extra_forbidden), different mechanism

This issue was drafted by an AI agent (OpenHands) on behalf of the user, who reviewed and approved the content before submission.

Dominant language
Python
Stars
1.4k
Forks
797
Avg merge
1d 17h
Merged PRs (30d)
354

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 OpenHands/software-agent-sdk

All issues in OpenHands/software-agent-sdk

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.