mcp-gateway: Instructions file for Codex

AGENTS.md: Operational Guidelines for AI Assistants

This repository (mcp-gateway) implements a Universal Multi-Tenant Model Context Protocol (MCP) reverse proxy and gateway service built on @thargy/mcp-server-core to adapt arbitrary 3rd-party MCP servers (HTTP and STDIO) for seamless operation behind Cloudflare Zero Trust tunnels and modern AI IDEs.

---

Critical Safety Invariants

1. NEVER COMMIT OR PUSH TO GIT: Do not run git commit, git push, or alter git history without express instruction from the user.
2. Strict ESM & TypeScript: The project uses NodeNext ESM (import ... from './file.js'). Every local import statement MUST include an explicit .js extension.
3. Seam-First Adapter Architecture: All upstream backends implement the IMcpBackendAdapter interface (HttpProxyAdapter, StdioProxyAdapter).
4. Test Speed & Network Isolation: Unit tests must execute in complete isolation from external networks using in-memory doubles or mocked HTTP/STDIO streams.

---

Architectural Rules

1. Unified Gateway Philosophy

• A single gateway service runs on the Docker server (ssh-docker.thargy.com:3007), exposing multi-tenant MCP endpoints and dedicated port listeners.
• Cloudflare Tunnel streams traffic via https://mcp.thargy.com/<path>/mcp.
• All requests benefit from @thargy/mcp-server-core features:
  • Immediate : heartbeat\n\n Cloudflare SSE stream priming.
  • subscriptions/listen notification streams.
  • Stateless JSON-RPC and stateful Streamable HTTP dual-mode content negotiation.
  • Constant-time Bearer token authentication.

2. Declarative Route Configuration (config.yaml)

Adding new 3rd-party MCP servers (e.g. Brave Search, SQLite, PostgreSQL) requires only adding a route definition to config.yaml:

routes:
  gh:
    type: http
    name: "github-mcp-server"
    targetUrl: "http://github-mcp-backend:8082"
    authHeaderEnv: "GITHUB_PERSONAL_ACCESS_TOKEN"

  brave:
    type: stdio
    name: "brave-search"
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-brave-search"]
    env:
      BRAVE_API_KEY: "${BRAVE_API_KEY}"