README
¶
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.
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
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.
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: truefor edge deployments - Path normalization enabled
-
headers_with_underscores_action: REJECT_REQUEST
Documentation
¶
Index ¶
- func CreateConsoleCore() zapcore.Core
- func CreateNewLoggerFromCore(core zapcore.Core) *zap.Logger
- func InitLogger(config TelemetryConfig) error
- func InitTracer(ctx context.Context, config TelemetryConfig) (func(context.Context) error, error)
- func RunServer(ctx context.Context, cfg *Config) error
- type Config
- type ServerInfo
- type TelemetryConfig
- type ToolRegistryConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CreateConsoleCore ¶
CreateConsoleCore returns a zapcore.Core that writes info/warn logs to stdout and error logs to stderr using a console encoder.
func CreateNewLoggerFromCore ¶
CreateNewLoggerFromCore creates a named zap.Logger from the given core with caller information enabled.
func InitLogger ¶
func InitLogger(config TelemetryConfig) error
InitLogger sets up the global logger to use the OTel bridge, allowing logs to be exported to OTel.
func InitTracer ¶
InitTracer initializes the OpenTelemetry tracer and returns a shutdown function
Types ¶
type Config ¶
type Config struct {
// SocketPath is the Unix domain socket path the gRPC server listens on.
SocketPath string
// ToolRegistryConfig configures how tools are loaded from OpenAPI specs.
ToolRegistryConfig *ToolRegistryConfig
// ServerInfo configures the identity and instructions for the MCP server.
ServerInfo ServerInfo
}
Config holds the configuration for the ext_proc gRPC server.
type ServerInfo ¶
type ServerInfo struct {
// Name is the server name reported to MCP clients.
Name string
// Version is the server version reported to MCP clients.
Version string
// Instructions is human-readable text returned to MCP clients.
Instructions string
}
ServerInfo holds the identity and instructions returned in the MCP initialize response.
type TelemetryConfig ¶
type TelemetryConfig struct {
// OtelEndpoint is the gRPC address of the OpenTelemetry Collector (e.g. "localhost:4317").
OtelEndpoint string
// ServiceName identifies this service in traces and logs.
ServiceName string
// ServiceVersion is the version string reported in telemetry resource attributes.
ServiceVersion string
}
TelemetryConfig holds the configuration for OpenTelemetry tracing and logging exporters.
type ToolRegistryConfig ¶
type ToolRegistryConfig struct {
// OpenAPISpecPattern is a glob pattern to match OpenAPI spec files for loading tools.
// For example, "specs/*.yaml" would load all YAML files in the specs directory.
OpenAPISpecPattern string
// ToolAllowlist is an optional list of tool names to allow. If empty, all tools loaded from the OpenAPI specs will be allowed.
ToolAllowlist []string
// StructuredOutput indicates whether to enable structured output for tools,
// which allows using outputSchema for response validation and structured content in tool responses.
StructuredOutput bool
}
ToolRegistryConfig defines the configuration for creating a toolRegistry from OpenAPI specs.
Source Files