Feature: mcp to grpc proxy

[jue-yin]

Add MCP Proxy Filter and gRPC Transcoder Handler

Overview

This PR adds two new extensions to Envoy:

1. MCP Proxy Filter (mcp_proxy) - Implements Model Context Protocol (MCP) server functionality
2. MCP to gRPC Handler (mcp_to_grpc) - Transforms MCP tool calls to gRPC requests

Features

MCP Proxy Filter

• Complete MCP server protocol implementation
• Support for tools list query (/tools/list)
• Support for tools call (/tools/call)
• Configurable server metadata (name, title, version, instructions)
• Support for structured content output
• Route-level configuration override support

MCP to gRPC Handler

• Transforms MCP tool calls to gRPC requests
• Protocol Buffer descriptor configuration support
• Automatic tool list and JSON Schema generation
• HTTP/gRPC transcoding support
• Configurable JSON output options
• Case-insensitive enum parsing support
• Output schema validation support

Technical Implementation

Core Components

• McpFilter: HTTP filter implementing MCP protocol handling
• McpToGrpcMcpHandler: Transforms MCP requests to gRPC calls
• TranscoderInputStreamImpl: Custom input stream implementation
• Complete Protocol Buffer and JSON Schema generation

Configuration Example

# MCP Proxy Filter Configuration
http_filters:
- name: envoy.filters.http.mcp_proxy
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.mcp_proxy.v3.McpProxy
    mcp_handler:
      name: envoy.http.mcp_handler.mcp_to_grpc
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.http.mcp_handler.mcp_to_grpc.v3.McpToGrpc
        proto_descriptor: "/path/to/service.pb"
        services: ["helloworld.Greeter"]
        include_output_schema: true
        print_options:
          add_whitespace: true
          preserve_proto_field_names: true
    server_name: "My MCP Server"
    server_title: "MCP to gRPC Bridge"
    server_version: "1.0.0"
    server_instructions: "This server provides gRPC services via MCP protocol"
    structured_content: true

Testing

need to add

Related Issues

#39174

[repokitteh-read-only]

Hi @jue-yin, welcome and thank you for your contribution.

We will try to review your Pull Request as quickly as possible.

In the meantime, please take a look at the contribution guidelines if you have not done so already.

🐱

Caused by: #40876 was opened by jue-yin.

see: more, trace.

[repokitteh-read-only]

CC @envoyproxy/api-shepherds: Your approval is needed for changes made to (api/envoy/|docs/root/api-docs/).
envoyproxy/api-shepherds assignee is @markdroth
CC @envoyproxy/api-watchers: FYI only for changes made to (api/envoy/|docs/root/api-docs/).

🐱

Caused by: #40876 was opened by jue-yin.

see: more, trace.

[guydc]

Are you also planning for mcp-proxy to be developed further to serve as a transparent proxy for existing MCP servers, utilizing MCP context awareness for tasks such as authentication, routing, and rate limiting?

[johnlanni]

@guydc Hello, I am on the same team as the author of this PR. My understanding is that Envoy natively supports direct proxy scenarios, but some additional capabilities such as observability for JSON RPC might be needed, right?

[guydc]

@guydc Hello, I am on the same team as the author of this PR. My understanding is that Envoy natively supports direct proxy scenarios, but some additional capabilities such as observability for JSON RPC might be needed, right?

In the current proposal, it seems that the mcp-proxy filter is focused on exposing existing REST/gRPC services as an MCP server:

• it requires a transcoding handler
• it "takes over" as the mcp server (providing mcp server metadata)

I wonder if mcp-proxy can also be used as a standalone and transparent filter that emits mcp context when proxying an existing MCP server. For example, by emitting relevant metadata from the mcp-proxy filter, it might be possible to build support for:

• rate limit based on the tool name being called
• route to an appropriate upstream
• provide richer access logs and metrics
• enforce different auth

[ahmad-ddog]

@guydc Hello, I am on the same team as the author of this PR. My understanding is that Envoy natively supports direct proxy scenarios, but some additional capabilities such as observability for JSON RPC might be needed, right?

In the current proposal, it seems that the mcp-proxy filter is focused on exposing existing REST/gRPC services as an MCP server:

• it requires a transcoding handler
• it "takes over" as the mcp server (providing mcp server metadata)

I wonder if mcp-proxy can also be used as a standalone and transparent filter that emits mcp context when proxying an existing MCP server. For example, by emitting relevant metadata from the mcp-proxy filter, it might be possible to build support for:

• rate limit based on the tool name being called
• route to an appropriate upstream
• provide richer access logs and metrics
• enforce different auth

Couldn't all these things be done by exposing the tool name in request metadata?

[ahmad-ddog]

How would that work with streamable http (especially the SSE and session-based part of it)?

[botengyao]

I wonder if mcp-proxy can also be used as a standalone and transparent filter that emits mcp context when proxying an existing MCP server. For example, by emitting relevant metadata from the mcp-proxy filter, it might be possible to build support for

yes, I think this is a legit use case that we can support at first, storing to metadata will work.

[wbpcode]

Wow, wow wow 👍

[github-actions]

This pull request has been automatically marked as stale because it has not had activity in the last 30 days. It will be closed in 7 days if no further activity occurs. Please feel free to give a status update now, ping for review, or re-open when it's ready. Thank you for your contributions!

[github-actions]

This pull request has been automatically closed because it has not had activity in the last 37 days. Please feel free to give a status update now, ping for review, or re-open when it's ready. Thank you for your contributions!