Skip to content

Non-ASCII base64 Mcp-Name header returns 500 instead of HEADER_MISMATCH #3817

Open

Description

@jbrown9513

Initial Checks

Release line

2.x (current stable)

Description

A tools/call whose Mcp-Name header uses the =?base64?...?= form with a non-ASCII byte in the payload gets a 500. It is one failed request, and the server keeps running.

The docstring on decode_header_value says "A malformed sentinel (bad base64, non-canonical base64, or bad UTF-8) yields None". None should become a HEADER_MISMATCH rejection.

It catches only binascii.Error, but b64decode raises a plain ValueError for non-ASCII text:

try:
decoded = base64.b64decode(payload, validate=True)
except binascii.Error:
return None

The modern POST handler does not catch it:

verdict = classify_inbound_request(decoded, headers=dict(request.headers))

The Mcp-Param-* check calls the same function, from reading the code:

decoded = decode_header_value(raw)

except ValueError: fixes it, since binascii.Error is a subclass.

Results on 2.3.0, with the script below. inbound.py is unchanged on main at af4c6f4.

b'echo' 200
b'=?base64?ZWNobw==?=' 200
b'=?base64?\xe9?=' 500

Example Code

import anyio, httpx2 as httpx
from mcp.server.mcpserver import MCPServer
from mcp_types.version import LATEST_MODERN_VERSION

mcp = MCPServer("demo")

@mcp.tool()
def echo(text: str) -> str:
    return text

async def main():
    app = mcp.streamable_http_app()
    body = {"jsonrpc": "2.0", "id": 1, "method": "tools/call",
            "params": {"name": "echo", "arguments": {"text": "hi"},
                       "_meta": {"io.modelcontextprotocol/protocolVersion": LATEST_MODERN_VERSION,
                                 "io.modelcontextprotocol/clientCapabilities": {}}}}
    async with app.router.lifespan_context(app):
        transport = httpx.ASGITransport(app=app, raise_app_exceptions=False)
        async with httpx.AsyncClient(transport=transport, base_url="http://127.0.0.1:8000") as c:
            for name in [b"echo", b"=?base64?ZWNobw==?=", b"=?base64?\xe9?="]:
                r = await c.post("/mcp", json=body, headers=[(b"mcp-protocol-version", LATEST_MODERN_VERSION.encode()),
                    (b"accept", b"application/json, text/event-stream"), (b"mcp-method", b"tools/call"), (b"mcp-name", name)])
                print(name, r.status_code)

anyio.run(main)

Python & MCP Python SDK

Python 3.12.12, MCP Python SDK 2.3.0

AI disclosure

refuzz, an LLM-driven fuzzer I built (Meta Muse Spark), found this bug. Claude Code wrote this report and ran the reproduction on 2.3.0.

Activity

  1. added
    bugSomething isn't working
    spec-2026-07-28Concerns the SDK's implementation of the 2026-07-28 MCP spec revision
    v2Affects the v2 line (2.x on main)
    on Nov 4, 2026
  2. media-ctrl commented on Nov 5, 2026

    @media-ctrl
  3. techaurah commented on Nov 5, 2026

    @techaurah

    Hi, we are TechAura. We can reproduce this and implement the scoped fix in decode_header_value — catching ValueError so a non-ASCII base64 sentinel returns None and becomes a HEADER_MISMATCH rejection instead of a 500 — with a test for the string form. Could a maintainer please assign this issue to @techaurah? We will open a PR only after assignment.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingspec-2026-07-28Concerns the SDK's implementation of the 2026-07-28 MCP spec revisionv2Affects the v2 line (2.x on main)

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions