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

MCPServer completion handler returning more than 100 values fails on 2026-07-28 sessions and violates the 100-item limit on 2025-11-25 sessions

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

Maintainers usually reply within 1 day

@musi22 is already working on this.

Since Oct 8, 2026.

  • #3660 by @musi22 — closed without merging

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
88/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
backend-api-design

Research direction

Start at the MCPServer.completion wrapper in mcp/server/mcpserver.py (lines ~759-766), which passes the handler's Completion through untouched; the 100-item cap lives in mcp_types/_v2026_07_28 and is enforced at runner.py:381, so the wrapper must truncate to 100 values and set total/has_more before validation, preserving handler-set values. Compare with the TypeScript SDK's createCompletionResult. Done means a regression test under tests/server/mcpserver/ using an in-memory Client passes for both mode="auto" (2026-07-28) and mode="legacy" (2025-11-25), returning 100 values with has_more=True.

Written by the indexing model from the issue text.

Description

bug spec-2026-07-28 v2
Initial Checks
Release line

2.x (current stable)

Description

An @mcp.completion() handler that returns more than 100 values behaves differently depending on the negotiated protocol version, and both behaviours are wrong:

  • 2026-07-28 session: the whole completion/complete request fails with -32603 "Handler returned an invalid result". The user gets no suggestions at all.
  • 2025-11-25 session: all values go out on the wire. The spec says values "Must not exceed 100 items", and total / hasMore are left unset, so the client can't tell the list was too long.

It's easy to hit with the filter-by-prefix pattern from docs/servers/completions.md. When the user hasn't typed anything yet (argument.value == ""), every candidate matches, so any handler over a list of more than 100 options (countries, time zones, repos, file names, and so on) fails as soon as the field is focused.

The 100-item cap is only enforced by the 2026-07-28 wire model (Completion.values: Annotated[list[str], Field(max_length=100)] in mcp_types/_v2026_07_28). runner.py:381 checks results against that model and turns the ValidationError into a generic INTERNAL_ERROR. The 2025-11-25 wire model has no such constraint, so nothing stops the oversize list there. The MCPServer.completion wrapper (server.py:759-766) passes the handler's Completion through as-is.

For comparison, the TypeScript SDK's McpServer truncates to 100 and fills the pagination hints (createCompletionResult: values.slice(0, 100), total: suggestions.length, hasMore: suggestions.length > 100).

Expected: the same handler works on both protocol versions. The client receives the first 100 values with total / hasMore telling it more exist, as Completion's own docstring ("total … can exceed the number of values actually sent") and the docs' total= / has_more= note describe.

Server log on the 2026-07-28 session:

ERROR    handler for 'completion/complete' returned an invalid result
pydantic_core._pydantic_core.ValidationError: 1 validation error for CompleteResult
completion.values
  List should have at most 100 items after validation, not 150 [type=too_long, ...]

I reported this and would like to fix it. Proposed approach: in the MCPServer.completion wrapper, when the handler returns more than 100 values, send the first 100 and set total (to the full count) and has_more=True. Values the handler set explicitly win. Handlers returning ≤100 values are unchanged. The lowlevel Server stays as it is, since a lowlevel handler builds the CompleteResult itself. I'd add a regression test in tests/server/mcpserver/ using an in-memory Client, covering both mode="auto" (2026-07-28) and mode="legacy" (2025-11-25). It's roughly 10 lines of source. If you'd prefer a different behaviour (for example, raising a clear error at the wrapper instead of truncating), I'm happy to do that.

I used an AI assistant to help narrow this down; I ran the reproduction myself on 2.3.0 and on main.

Example Code
import anyio
from mcp_types import Completion, PromptReference
from mcp.client import Client
from mcp.server.mcpserver import MCPServer

COUNTRIES = [f"country-{i:03}" for i in range(150)]

mcp = MCPServer("demo")


@mcp.prompt()
def travel(country: str) -> str:
    return f"Plan a trip to {country}"


@mcp.completion()
async def complete(ref, argument, context):
    # Filter by the typed prefix, as in docs/servers/completions.md; an empty prefix matches everything.
    return Completion(values=[c for c in COUNTRIES if c.startswith(argument.value)])


async def main() -> None:
    for mode in ("auto", "legacy"):
        async with Client(mcp, mode=mode) as client:
            try:
                result = await client.complete(
                    ref=PromptReference(type="ref/prompt", name="travel"),
                    argument={"name": "country", "value": ""},
                )
                c = result.completion
                print(f"{client.protocol_version}: {len(c.values)} values, total={c.total}, has_more={c.has_more}")
            except Exception as e:
                print(f"{client.protocol_version}: {type(e).__name__}: {e}")


anyio.run(main)

Output:

2026-07-28: MCPError: Handler returned an invalid result
2025-11-25: 150 values, total=None, has_more=None
Python & MCP Python SDK
Python 3.12.12, mcp 2.3.0, pydantic 2.13.5 (PyPI release)
Python 3.14.0, mcp main @ 91941ed, pydantic 2.12.5
Windows 11
Dominant language
Python
Stars
24.5k
Forks
4k
Avg merge
18h 31m
Merged PRs (30d)
38

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 modelcontextprotocol/python-sdk

All issues in modelcontextprotocol/python-sdk

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.