mcp-proxy: Instructions file for Codex

AGENTS.md

Overview

mcp-proxy is a config-driven MCP (Model Context Protocol) reverse proxy built in Rust. It aggregates multiple MCP backends behind a single HTTP endpoint with per-backend middleware, authentication, and observability. Built on tower-mcp and the tower middleware ecosystem.

Package name: mcp-proxy. Binary name: mcp-proxy. Library name: mcp_proxy.

Project structure

src/
  main.rs          # CLI entry point (clap), logging setup
  lib.rs           # Library root, re-exports Proxy and ProxyConfig
  proxy.rs         # Core: builds proxy, middleware stack, and axum router
  lifecycle.rs     # Shared runtime owner, scoped transport cancellation and cleanup leases
  server.rs        # Owned HTTP1/HTTP2 connection/stream tasks and bounded drain
  config.rs        # TOML/YAML config parsing, validation, all config types
  builder.rs       # Fluent programmatic configuration builder
  discovery.rs     # Search index and complete tool schema store
  mcp_json.rs      # Import Claude-style .mcp.json configurations
  ws_transport.rs  # Outbound WebSocket transport
  skills.rs        # Management prompts bundled from src/skills/
  admin.rs         # HTTP admin API (/admin/backends, /admin/health, etc.)
  admin_tools.rs   # MCP admin tools (proxy/ namespace, via ChannelTransport)
  reload.rs        # Owned file watcher and admitted plain backend connections
  reload_policy.rs # Frozen startup policy admission and safe last-attempt status
  test_util.rs     # MockService, ErrorMockService, call_service helper

  # Global middleware (wraps the entire proxy, applied in proxy.rs)
  access_log.rs    # Structured access logging (AccessLogService, target: mcp::access)
  audit.rs         # Audit completion metadata/error codes, excluding private bodies
  alias.rs         # Tool renaming (AliasService)
  filter.rs        # Capability filtering -- allow/deny lists, glob patterns (CapabilityFilterService)
  inject.rs        # Argument injection into tool calls (InjectArgsService)
  mirror.rs        # Traffic mirroring to canary backends (MirrorService)
  cache.rs         # Scoped response caching, shared budgets and generation ownership
  cache/           # Bounded SQLite blocking I/O and Redis indexed storage
  coalesce.rs      # Request deduplication (CoalesceService)
  validation.rs    # Argument size limits (ValidationService)
  metrics.rs       # Scoped/shared Prometheus ownership, bounded namespace attribution
  telemetry.rs     # Privacy-preserving MCP/HTTP spans and explicit OTLP provider factory
  rbac.rs          # Role-based access control (RbacService)
  token.rs         # Legacy identity-only helper; no credential forwarding
  management.rs    # Explicit HTTP/MCP management authority and credential-bound sessions
  invocation.rs    # Search wrapper resolution preserving caller/request context
  bearer_scope.rs  # Per-token tool scoping and claims
  introspection.rs # OAuth token introspection and JWT fallback
  param_override.rs # Tool parameter hiding, renaming, and defaults
  composite.rs     # Composite tool fan-out
  canary.rs        # Weighted canary routing
  failover.rs      # Ordered backend failover

  # Per-backend middleware (applied per-backend in proxy.rs and reload.rs)
  outcome.rs       # Shared response classification, cache admission, hedge adapter
  retry.rs         # tower-resilience retry layer, exponential backoff, budgets
  outlier.rs       # Outlier detection and ejection (OutlierDetectionLayer)

tests/
  integration.rs   # Middleware composition tests with in-process backends via ChannelTransport
  e2e.rs           # Full proxy pipeline tests with in-process backends
  http_e2e.rs      # Real HTTP transport and authentication tests
  configured_sessions.rs # Configured embedding/CLI full-session transport and policy matrix
  support/        # Reusable bounded session/application/backend/OAuth fixtures
  health_probes.rs # Configured proxy process probes and auth boundaries
  replica_sessions.rs # Two real CLIs through NGINX affinity, retirement/loss and reinitialize
  reload_runtime.rs # Watched-file CLI add/replace tests and watcher ownership
  coalesce_runtime.rs # Configured HTTP/MCP capacity, expiry and recovery
  outcome_runtime.rs # Configured cache recovery, breaker state, hedge winners and metrics
  retry_runtime.rs # Configured authenticated sessions and exact volume-budget attempt counts
  outlier_runtime.rs # Competing configured calls and raw backend removal/re-registration
  shutdown_runtime.rs # SIGTERM/SSE, short drain, construction/drop and stdio reap regressions
  cli_logging.rs   # Real CLI JSON/text/OTel request records and privacy regressions
  outbound_headers.rs # Actual HTTP requests and WebSocket handshake headers
  discovery_schemas.rs # Tool schema retrieval and reindex behavior
  chaos.rs         # Fault injection and resilience recovery regressions
  cache_backends.rs # Real Redis containers and temporary SQLite databases
  config_properties.rs # Property tests for config validation
  invariant_properties.rs # Config/authorization/transform properties and paused-clock schedules
  protocol_contracts.rs # Configured library/CLI legacy baseline and modern feature contracts
  examples.rs      # Load and validate every example TOML config

examples/
  *.toml           # Example proxy configs for different deployment patterns
  docker-compose/  # Docker compose example with HTTP backend