[Frontend][gpt-oss] Support all MCP servers for gpt-oss

[alecsolder]

Purpose

This PR is an implementation of #26703

Note: This PR is really big, but there was a lot that had to be cleaned up at the same time. A large amount of the code is from adding tests to existing code and a MCP server to test with and new MCP tests.

There are three main motivations:

• vLLM should support integrating with all MCP servers
  • TODO: Test with enterprise ones like Github
• Clean up gpt-oss tool specific code paths in vLLM
  • Tools and models change, but MCP is a protocol meant to support all models
  • Sets the stage for full MCP integration for all tool calling models
• Avoid losing information due to lossy OpenAI types for output
  • An example below

# What you can return to the user on the ResponsesAPI for this tool call with the OpenAI types.
class ActionOpenPage(TypedDict, total=False):
    type: Required[Literal["open_page"]]
    url: Required[str]
# The interface for the actual tool call the model does
open_link(ctx: Context,
    id: Union[int, str] = -1,
    cursor: int = -1,
    loc: int = -1,
    num_lines: int = -1,
    view_source: bool = False,
    source: Optional[str] = None)

This feature is similar to the concept of “connectors” because we still don’t support users specifying arbitrary MCP servers by URL yet, the list is static and owned by the server, which is more similar to the concept of OpenAI MCP Connectors.

Test Plan

Run the provided simple Memory MCP server using:

python tests/entrypoints/openai/memory_mcp_server.py 
# 8765 is the default port

Then register it with your vLLM responses API server with:

CUDA_VISIBLE_DEVICES=6 vllm serve openai/gpt-oss-20b --tool-server=localhost:8765

And then try it out with something like:

curl http://localhost:8000/v1/responses \
  -H "Content-Type: application/json" -N \
  -d '{
        "model": "openai/gpt-oss-20b",
        "input": "Show me that the memory tool works.",
        "tools": [
          {
            "type": "mcp",
            "server_label": "memory", 
            "server_url": "ignored"
          }
        ],
        "enable_response_messages": true
      }'

Test Result

Passed

[mergify]

This pull request has merge conflicts that must be resolved before it can be
merged. Please rebase the PR, @alecsolder.

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[gemini-code-assist]

Code Review

This pull request introduces a significant and well-executed refactoring to support arbitrary MCP (Model Context Protocol) servers, moving away from hardcoded tool logic. The changes generalize tool handling by introducing concepts like tool namespaces, normalization of legacy tool types, and a distinction between elevated and custom tools. The addition of comprehensive tests, including a standalone MCP server, ensures the new system is robust. Overall, this is a great improvement for the tool integration capabilities of vLLM. I have one piece of feedback regarding some debugging code that should be removed.

[gemini-code-assist]

These print statements appear to be for debugging purposes. They should be removed before merging to avoid leaking potentially sensitive information from user requests into the server logs and to reduce log noise in production environments.

[alecsolder]

thank you gemini :)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

[chatgpt-codex-connector]

Importing MCP client unconditionally breaks deployments without MCP

The module now imports from mcp import ClientSession and sse_client at top level. Any process that imports vllm.entrypoints.tool_server (e.g., the default API server) will immediately raise ImportError when the optional mcp package is not installed, even if MCP tooling is never used. The previous implementation delayed the import inside MCPToolServer.__init__ and only failed when the optional feature was exercised. This regression forces all installations to ship the MCP dependency, which will crash existing configurations that do not provide it.

Useful? React with 👍 / 👎.

[qandrew]

thanks for putting this together! However the PR is a bit large to review thoroughly, can you split into smaller pieces? if you have 3 main motivations, can you split them into 3 separate PRs? a 4th pr could add memory_mcp_server, test_memory_mcp_server logic too

[qandrew]

nit: this file should go in the mcp folder

[qandrew]

i think i general we shouldn't need to do E2E tests for all functionality testing, ideally we can mock the client/server and reduce CI load. You might run into CI memory issues (i had some here eb6dd74) by spinning up more servers within the same CI step

[mergify]

This pull request has merge conflicts that must be resolved before it can be
merged. Please rebase the PR, @alecsolder.

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[bbrowning]

These comments (and the similar ones for the elevated test case) are the most concise description of custom tools vs elevated/system/builtin (naming is hard) tools that I've seen, and help me really understand the difference. And as someone that has studied the Harmony format, I immediately understand the implications of this.

It feels like we need some user-facing documentation about this as well, with something to help the user know if they want their tools to be in GPT_OSS_SYSTEM_TOOL_MCP_LABELS or not and what the implications of that are on the tool calls generated or on the execution of those tool calls.