Skip to content

README.md

Latest commit

 

History

History
183 lines (132 loc) · 6.23 KB

README.md

File metadata and controls

183 lines (132 loc) · 6.23 KB
Raw

envoy-mcp-openapi-processor

An Envoy external processor that transforms Model Context Protocol (MCP) requests into upstream HTTP API calls based on OpenAPI specifications.

The external processor server communicates only with Envoy over gRPC via a Unix domain socket. Envoy owns all downstream client and upstream service connections, while the processor inspects and can mutate request and response data relayed by Envoy.

Installation

go get github.com/ing-bank/envoy-mcp-openapi-processor

Quick Start

See examples/mcp-server for a complete working example including Envoy proxy configured to use the envoy-mcp-openapi-processor server.

Supported MCP Protocol Versions

The processor is a dual-era MCP server supporting 2025-06-18, 2025-11-25 and 2026-07-28. The two eras have disjoint entry points, so every request selects one unambiguously:

  • Legacy era (2025-06-18, 2025-11-25): the client starts with the initialize handshake and declares no version on subsequent requests. Version negotiation never yields a modern version, so a client that asks for one over the handshake is answered with a version it can actually use statefully.
  • Modern era (2026-07-28): there is no handshake. The mandatory server/discover RPC replaces initialize, and every request carries its protocol version in params._meta (io.modelcontextprotocol/protocolVersion) and mirrors it in the MCP-Protocol-Version header, alongside Mcp-Method (and Mcp-Name for tools/call). Those headers are validated against the JSON-RPC body and mismatches are refused with HTTP 400 and JSON-RPC error -32020. Results carry resultType and the serverInfo _meta entry, and an unknown method answers HTTP 404 rather than the legacy 200.

Result caching

Modern server/discover and tools/list results carry fixed cache hints: ttlMs: 300000 (five minutes) and cacheScope: "private". The tool list changes only on redeploy, and an ext_proc filter cannot push notifications/tools/list_changed, so the TTL is what brings a client back. Five minutes bounds how long a client may keep using a retired list. Re-fetching is cheap, since both results are served from memory and never reach the upstream API.

OpenTelemetry

To enable export of logs and traces to an OpenTelemetry collector, use one of the options below. If neither is used, the server runs with a no-op tracer provider and a no-op logger.

Option 1: Use provided initialization functions

package main

import (
	"context"

	mcp_proc "github.com/ing-bank/envoy-mcp-openapi-processor"
)

func main() {
	telemetryConfig := mcp_proc.TelemetryConfig{
		OtelEndpoint:   "otel-collector:4317",
		ServiceName:    "mcp-sidecar",
		ServiceVersion: "1.0.0",
	}
	ctx := context.Background()
	err := mcp_proc.InitLogger(telemetryConfig)
	// ...
	tracerShutdown, err := mcp_proc.InitTracer(ctx, telemetryConfig)
	// ...
	var cfg mcp_proc.Config
	// ...
	mcp_proc.RunServer(ctx, &cfg)
}

Option 2: Bring your own provider

Set the global tracer provider by calling otel.SetTracerProvider(myTracerProvider) and the global zap logger by calling zap.ReplaceGlobals(myLogger) before starting the server.

Development

Tests

To run all tests, execute the following command:

make test

To check the test coverage, execute the following command:

make coverage-check

E2E tests

To run the end-to-end suite (spins up Envoy, the processor, and a mock upstream via Docker Compose, then exercises MCP <=> REST translation), execute the following command:

make e2e

Requires Docker. On failure, container logs are captured in e2e/last-run.log.

Fuzz tests

Run server handler fuzz tests one at a time:

make fuzz-request
make fuzz-response

Each command runs until stopped with Ctrl+C and reports any issues found.

DNS Rebinding Protection

The processor validates the Host/:authority and Origin headers of every request. By default only loopback hostnames are accepted: localhost, 127.0.0.1 and ::1 (any port); anything else is refused with HTTP 403. This protects unauthenticated localhost deployments against DNS rebinding attacks where a malicious website's DNS resolves to 127.0.0.1 so the victim's browser sends same-origin requests to the local server.

A missing Host header is rejected (fail closed). A missing Origin header is accepted (non-browser clients do not send one), but a present Origin must be a URL whose hostname is allowed.

Deployments serving other domains configure them via Config.AllowedHosts:

cfg := &mcp_proc.Config{
    // ...
    AllowedHosts: []string{"mcp.example.com"},
}

Matching is case-insensitive and ignores ports. A non-empty list replaces the localhost default — include "localhost" explicitly if it should remain allowed.

Each entry is one of:

  • "*" — match any host. This disables DNS rebinding protection, so use it only on trusted networks.
  • "*.example.com" — match any subdomain at any depth (foo.example.com, a.b.example.com) but not the apex example.com.
  • "mcp.example.com" — exact match.

Security Checklist

Before deploying to production, we advise to verify if the following controls are in place

Container Security

  • Container runs as non-root user
  • Read-only root filesystem where possible
  • No privileged mode
  • Resource limits (CPU, memory) configured
  • seccomp profile applied
  • AppArmor/SELinux enabled
  • Container image scanned for CVEs
  • Image signed and verified

Envoy Configuration

  • TLS configured for downstream connections
  • TLS configured for upstream connections
  • Buffer limits set (≤32KB for edge deployments)
  • Connection limits configured
  • Stream limits configured (≤100 concurrent for HTTP/2)
  • Timeouts configured (connection, stream, request)
  • Overload manager enabled
  • Admin endpoint restricted to localhost
  • use_remote_address: true for edge deployments
  • Path normalization enabled
  • headers_with_underscores_action: REJECT_REQUEST