> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Protocol Support

> MCP protocol versions, transports, and feature support across remote, virtual, OpenAPI, and stdio MCP servers on the TrueFoundry AI Gateway.

This page documents which parts of the [Model Context Protocol](https://modelcontextprotocol.io/specification) the TrueFoundry MCP Gateway supports, for each way an MCP server can be exposed through the gateway:

1. **Remote MCP servers** accessed by third-party clients (Cursor, Claude Code, VS Code, custom agents) through the gateway
2. **Remote MCP servers** accessed from the [Playground](#playground) and MCP server details page
3. **[Virtual MCP servers](/docs/ai-gateway/mcp/virtual-mcp-server)** that curate tools from multiple servers
4. **[OpenAPI MCP servers](/docs/ai-gateway/mcp/openapi-mcp-server)** generated from OpenAPI specifications
5. **[Hosted stdio MCP servers](/docs/ai-gateway/mcp/stdio-mcp-server)** run from a command via the gateway's stdio proxy

Across these surfaces the gateway situationally acts as an **MCP server** toward your clients and as an **MCP client** toward upstream servers — [Gateway Roles and Feature Support](#gateway-roles-and-feature-support) covers both.

## Gateway Roles and Feature Support

### Gateway as an MCP Server

The gateway serves MCP to your clients in two modes: as a **direct proxy** for remote and hosted stdio MCP servers, and as a **gateway-implemented server** for virtual and OpenAPI MCP servers. In both modes it handles authorization itself, independently of the upstream server.

#### Authorization

The gateway authenticates clients itself — 401 responses carry `WWW-Authenticate` challenges pointing at per-server RFC 9728 protected-resource metadata endpoints (`/.well-known/oauth-protected-resource/...`) — and acquires, stores, and refreshes upstream tokens on the user's behalf; see [MCP Gateway Auth & Security](/docs/ai-gateway/mcp/mcp-gateway-auth-security).

| Feature                                | 2025-03-26                                 | 2025-06-18                                             | 2025-11-25                                             | 2026-07-28                                             |
| -------------------------------------- | ------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------ |
| OAuth 2.1 authorization                | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" />             | <Icon icon="circle-check" color="green" />             | <Icon icon="circle-check" color="green" />             |
| Protected resource metadata (RFC 9728) | —                                          | <Icon icon="circle-check" color="green" />             | <Icon icon="circle-check" color="green" />             | <Icon icon="circle-check" color="green" />             |
| Dynamic client registration (RFC 7591) | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" />             | <Icon icon="circle-check" color="green" />             | <Icon icon="circle-check" color="green" />             |
| Resource indicators (RFC 8707)         | —                                          | <Icon icon="circle-check" color="green" /><sup>1</sup> | <Icon icon="circle-check" color="green" /><sup>1</sup> | <Icon icon="circle-check" color="green" /><sup>1</sup> |
| OpenID Connect discovery               | —                                          | —                                                      | <Icon icon="circle-check" color="green" />             | <Icon icon="circle-check" color="green" />             |
| Client ID Metadata Documents           | —                                          | —                                                      | <Icon icon="circle-x" color="red" />                   | <Icon icon="circle-x" color="red" />                   |

**Notes:**

1. The `resource` parameter is sent automatically with dynamic client registration, otherwise opt-in via the MCP server's auth configuration.

#### Direct Proxy

For remote MCP servers and [hosted stdio MCP servers](/docs/ai-gateway/mcp/stdio-mcp-server) the gateway is a **transparent proxy**: JSON-RPC bodies are forwarded unmodified, the protocol version is negotiated end to end, and the spec's protocol headers (`MCP-Protocol-Version`, `Mcp-Method`, `Mcp-Name`, `Mcp-Param-*`) are forwarded by default.

| Feature                          | 2025-03-26                                 | 2025-06-18                                 | 2025-11-25                                 | 2026-07-28                                 |
| -------------------------------- | ------------------------------------------ | ------------------------------------------ | ------------------------------------------ | ------------------------------------------ |
| Lifecycle (`initialize`, `ping`) | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> |
| Tools                            | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> |
| Prompts                          | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> |
| Resources                        | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> |
| Resource subscriptions           | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> |
| Completions                      | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> |
| Logging                          | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | —                                          |
| Sampling and roots               | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> |
| Elicitation                      | —                                          | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> |
| Notifications                    | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> |
| Tasks                            | —                                          | —                                          | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> |

Incremental spec additions — pagination, audio content, icons, `title`/`_meta` fields, and SSE stream resumability — are all forwarded transparently by the gateway from the revision that introduced them.

#### Gateway-Implemented Servers

[Virtual](/docs/ai-gateway/mcp/virtual-mcp-server) and [OpenAPI](/docs/ai-gateway/mcp/openapi-mcp-server) MCP servers are implemented by the gateway itself over streamable HTTP at fixed protocol version `2025-06-18`; unsupported methods return "method not found". For virtual servers, `tools/list` merges and de-duplicates tools from all backing servers and `tools/call` routes each call to the right one; for OpenAPI servers, tool calls are translated into HTTP requests against your API.

| Feature                                            | Status                                               |
| -------------------------------------------------- | ---------------------------------------------------- |
| Lifecycle (`initialize`, `ping`)                   | <Icon icon="circle-check" color="green" /> Supported |
| Tools (`tools/list`, `tools/call`)                 | <Icon icon="circle-check" color="green" /> Supported |
| Resources, prompts, completions, logging           | <Icon icon="circle-x" color="red" /> Not supported   |
| Sampling, elicitation, roots                       | <Icon icon="circle-x" color="red" /> Not supported   |
| Server-push notifications (list-changed, progress) | <Icon icon="circle-x" color="red" /> Not supported   |
| Extensions                                         | <Icon icon="circle-x" color="red" /> None advertised |

### Gateway as an MCP Client

Scenarios where the gateway connects out to MCP servers with its own internal client:

* **Virtual MCP servers** — connections to each backing server
* **[Playground](#playground) and MCP server details page** — listing and trying tools, prompts, and resources from the TrueFoundry UI

The internal client probes streamable HTTP first with automatic fallback to legacy HTTP+SSE, negotiates protocol versions up to `2025-11-25`, and handles upstream OAuth (registration, discovery, grants, and refresh — see [MCP Gateway Auth & Security](/docs/ai-gateway/mcp/mcp-gateway-auth-security)).

| Feature                                      | 2025-03-26                                 | 2025-06-18                                 | 2025-11-25                                 | 2026-07-28                           |
| -------------------------------------------- | ------------------------------------------ | ------------------------------------------ | ------------------------------------------ | ------------------------------------ |
| Lifecycle (`initialize`, `ping`)             | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-x" color="red" /> |
| Tools                                        | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-x" color="red" /> |
| Prompts                                      | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-x" color="red" /> |
| Resources (incl. templates)                  | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-check" color="green" /> | <Icon icon="circle-x" color="red" /> |
| Resource subscriptions, completions, logging | <Icon icon="circle-x" color="red" />       | <Icon icon="circle-x" color="red" />       | <Icon icon="circle-x" color="red" />       | <Icon icon="circle-x" color="red" /> |
| Sampling, elicitation, roots                 | <Icon icon="circle-x" color="red" />       | <Icon icon="circle-x" color="red" />       | <Icon icon="circle-x" color="red" />       | <Icon icon="circle-x" color="red" /> |
| Tasks                                        | —                                          | —                                          | <Icon icon="circle-x" color="red" />       | <Icon icon="circle-x" color="red" /> |

### Extensions

On the direct-proxy path, [extension](https://modelcontextprotocol.io/extensions/overview) negotiation and extension methods are forwarded unmodified; whether an extension works depends on your client and the upstream server.

| Extension                          | Identifier                                         | Status for remote servers                                                                                                                                                                                  |
| ---------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tasks                              | `io.modelcontextprotocol/tasks`                    | <Icon icon="circle-check" color="green" /> Forwarded — verified end to end at `2025-11-25` (experimental form); the `2026-07-28` extension form is expected to forward but is not yet verified             |
| MCP Apps (interactive UI elements) | `io.modelcontextprotocol/ui`                       | <Icon icon="circle-check" color="green" /> Forwarded — capability negotiation and tool `_meta` pass through unmodified                                                                                     |
| OAuth Client Credentials           | `io.modelcontextprotocol/oauth-client-credentials` | <Icon icon="circle-check" color="green" /> Gateway-managed — the gateway performs client-credentials (2LO) flows itself; see [MCP Gateway Auth & Security](/docs/ai-gateway/mcp/mcp-gateway-auth-security) |
| Enterprise-Managed Authorization   | —                                                  | <Icon icon="clock" color="orange" /> Coming soon — gateway-managed bridging of the enterprise flow                                                                                                         |

## Playground

The Playground and the MCP server details page interact with MCP servers through the gateway's [internal MCP client](#gateway-as-an-mcp-client):

| Operation                                    | Status                                                                                                              |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| List and call tools                          | <Icon icon="circle-check" color="green" /> Supported                                                                |
| List and get prompts                         | <Icon icon="circle-check" color="green" /> Supported                                                                |
| List and read resources                      | <Icon icon="circle-check" color="green" /> Supported                                                                |
| List resource templates                      | <Icon icon="circle-check" color="green" /> Supported                                                                |
| Elicitation                                  | <Icon icon="circle-x" color="red" /> Not supported                                                                  |
| Sampling                                     | <Icon icon="circle-x" color="red" /> Not supported                                                                  |
| Resource subscriptions, completions, logging | <Icon icon="circle-x" color="red" /> Not supported                                                                  |
| Tasks (task-augmented tool calls)            | <Icon icon="circle-x" color="red" /> Not supported — tool calls run synchronously                                   |
| MCP Apps (interactive UI)                    | <Icon icon="circle-x" color="red" /> Not supported — the playground does not declare the extension or render app UI |

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="My client sends the MCP-Protocol-Version header. Is it forwarded?">
    Yes. `MCP-Protocol-Version` and the `Mcp-*` header family (`Mcp-Method`, `Mcp-Name`, `Mcp-Param-*`) are forwarded to upstream servers by default, alongside `content-type`, `accept`, `mcp-session-id`, and `last-event-id`. The forwarded header set remains configurable at the gateway deployment level.
  </Accordion>

  <Accordion title="Does the gateway change my session behavior?">
    Sessions (`mcp-session-id`) are forwarded between your client and the upstream server without modification.
  </Accordion>

  <Accordion title="Which transport should my client use?">
    Use streamable HTTP. It is the current MCP standard, is preferred by the gateway in both directions, and is required for virtual, OpenAPI, and stdio MCP servers. Legacy HTTP+SSE is supported only for remote MCP servers, for compatibility with older servers and clients.
  </Accordion>
</AccordionGroup>