Skip to content

application

Switchboard

active

Private capability gateway that exposes curated upstream tools through one identity-aware MCP endpoint.

GitHub repository

Source: README.md
Commit: 7405335892b964893384d2998e66d6d7db89824e
Source updated:  ·  Edit this page

Switchboard is a private capability gateway for MCP. It gives an agent one curated endpoint while applications keep ownership of their business rules, authorization, durable state, auditing, and safety workflows.

Use it to compose internal APIs and existing MCP servers into profiles with exact tool permissions, identity-aware sessions, bounded egress, and a single client connection.

Highlights

  • Streamable HTTP and stdio MCP transports
  • Declarative REST, remote MCP, and local module capabilities
  • Profile and exact-tool authorization policies
  • OAuth/OIDC or Cloudflare Access identity-bound sessions
  • Capability discovery and dynamic activation
  • Environment-backed credentials; manifests contain no secrets
  • Mandatory fail-closed egress policy with exact destinations and CIDRs
  • Structured audit events and Prometheus-compatible metrics

Switchboard is the composition layer, not a replacement for upstream safety. A DNS change, publication, or destructive operation still uses the upstream application's native plan, confirmation, revision, and rollback workflow.

Place in the agent tooling stack

Switchboard is the front door when one agent needs a curated set of tools. It can expose Wayminder for durable cross-session knowledge and Rendercase for immutable, reviewable web artifacts, alongside other independently secured applications. Those services remain authoritative for their own data, authorization, and audit records; Switchboard only authenticates the caller, selects the permitted tools, and forwards calls through a bounded connection.

Use the services directly when a client needs only one of them. Use Switchboard when a single identity-aware endpoint, exact-tool policy, discovery, or bounded egress materially simplifies the client. Do not use Wayminder as an artifact store, Rendercase as durable agent memory, or Switchboard as a second database for either service.

Quick start

Requirements: Go 1.27.1 or newer. 

cp switchboard.example.json switchboard.json
cp capabilities/rilldns.example.json capabilities/rilldns.json

export RILLDNS_MCP_URL=https://rilldns.example.com/mcp
export RILLDNS_MCP_TOKEN=replace-me

go run ./cmd/switchboard -config switchboard.json

Connect an MCP client to http://127.0.0.1:8090/mcp. Health endpoints are available at /healthz, /readyz, and /metrics.

The multi-architecture container image is published at ghcr.io/kilo666mj/switchboard. Mount the configuration and capability manifests read-only, pass secrets through a protected environment file, and set the container configuration to listen on 0.0.0.0:8090. Bind the published port to loopback unless a trusted reverse proxy provides the external boundary. See the operator guide for an example.

Example profile: 

{
  "profile": "infrastructure-read",
  "tool_policy": "infrastructure-read",
  "profiles": {
    "infrastructure-read": ["rilldns", "fleetglass"],
    "publishing": ["rendercase"]
  }
}

Capability credentials are referenced by environment variable: 

{
  "headers": {
    "Authorization": {"env": "SERVICE_TOKEN", "prefix": "Bearer "}
  }
}

Do not put credential values in configuration or capability manifests.

Authentication and permissions

The stateless /mcp endpoint supports loopback-only unauthenticated use or a static bearer credential of at least 32 bytes. The stateful /mcp/sessions endpoint supports unique static clients, OAuth/OIDC resource-server authentication, and Cloudflare Access assertions from a trusted ingress.

When workload identities must coexist with OAuth or Cloudflare Access, use the provider's static_client_allowlist to enable only named entries from clients. It is mutually exclusive with the global allow_static_clients migration switch.

OAuth and Cloudflare identities map verified subjects and groups to profiles and exact tool policies. Cloudflare Access is optional and is not enabled by default. Its origin must reject bypass traffic, and the trusted proxy must strip client-supplied assertion headers before injecting its verified assertion.

Inspect effective authorization without changing it: 

switchboard permissions report -config switchboard.json
switchboard permissions lint -config switchboard.json
switchboard permissions lint -config switchboard.json -strict
switchboard permissions explain -config switchboard.json \
  -provider oauth -policy readers
switchboard permissions diff -config switchboard.json \
  -against proposed.json -provider oauth -policy readers

Security model

  • Non-loopback stateless HTTP requires a bearer credential.
  • Identity sessions fail closed when no policy matches.
  • Requests containing both OAuth and Cloudflare Access credentials are rejected.
  • Upstream secrets stay in the process environment.
  • The mandatory egress policy restricts exact destinations and CIDRs and resists DNS rebinding by validating and directly dialing resolved addresses.
  • TLS verification cannot be disabled for upstream MCP connections.
  • Every gateway and identity binding names an explicit tool policy; omitted tools deny by default.
  • Native mutating tools retain upstream approval and confirmation semantics.
  • Audit events omit tool arguments, results, and error text.
  • Never attach a debug MCP logger in a sensitive deployment because upstream SDK debug output may contain tool arguments.
  • Do not expose /metrics publicly; restrict it to the monitoring path at the reverse proxy or network boundary.

Review the examples before exposing Switchboard outside a trusted network.

Documentation

Status

Switchboard is deployed and actively used, but its configuration surface may continue to evolve before a stable 1.0 release. Releases and deployments should use the repository's privacy, dependency, and archive-verification gates.

License

MIT