MCP gateway

# Day one: no manifests. Everything runs and is journaled; nothing is blocked.
reversi-gateway --upstream-cmd npx --upstream-arg -y --upstream-arg my-mcp-server

# Later: enforce with manifests and a policy.
reversi-gateway --manifests ./manifests --policy ./policy.yaml \
  --upstream-cmd npx --upstream-arg -y --upstream-arg my-mcp-server
reversi-gateway --config gateway.yaml --manifests ./manifests      # anything more

​

Observe first

reversi-gateway: no manifests yet, so starting in observe mode: everything runs and is journaled. Run `reversi suggest-manifest` to draft manifests for what the upstream offers.

• Manifests come from --manifests, REVERSI_MANIFESTS, manifests: in reversi.config.yaml, or ./manifests if that folder exists.
• An explicit --mode or mode: always wins. Without one: observe when no manifests loaded, enforce otherwise.
• The mode is read at start. After you add manifests, restart to leave the automatic observe mode.

Reversi gateway running in observe mode.

WARN   fs.read_file - no manifest; treated as a change that could not be undone
WARN   fs.write_file - no manifest; treated as a change that could not be undone
...

0 classified, 0 unclassified reads, 9 unclassified changes, 0 destructive without a manifest.

9 tools have no manifest. They run (nothing is blocked) and are journaled as unclassified. Draft manifests with: reversi suggest-manifest.

​

Modes

​

What happens to a call

1. Manifest and scope. A tool with no manifest (in enforce mode), a draft manifest, or a permission outside the session’s scope is blocked.
2. Schema checks (below), then policy, content checks, kill switch (policy, content checks).
3. Approval if required: the call is blocked with the approval id, and the agent retries after an approver decides (approvals).
4. Journal the intent (write-ahead), forward to the upstream, journal the outcome. The upstream result is returned unchanged. An isError result is journaled as failed; a transport error or timeout as uncertain.

​

Schema validation

​

MCP annotations are hints

​

Schema drift

​

Timeout and retry

- tool: crm.lookup
  effect: read_only
  permission: crm:read
  timeout_ms: 10s
  retry: { attempts: 3, base_ms: 200, max_ms: 5s }

• timeout_ms: the gateway stops waiting after this long and journals the step as uncertain (the upstream may still have acted).
• retry repeats a failed or timed-out forward with exponential backoff. It is accepted only for read_only and idempotent tools; the manifest is rejected otherwise, and the gateway ignores retries for any other effect. Retrying a change could repeat it.
• Defaults when retry is given: 3 attempts, 200 ms base, 5 s cap (1 to 10 attempts).

​

Verification during rollback

​

Hot reload

​

Config

mode: enforce                 # enforce | advise | observe
unclassified_reads: block     # block | observe (see above)
validate_schemas: true
actor: dev-laptop             # for unauthenticated sessions (default mcp-client)
permissions: [fs:read, fs:write]   # scope of each session; default: every permission in the manifests
upstreams:
  - name: github
    url: https://mcp.example.com/mcp          # Streamable HTTP
    headers: { Authorization: "Bearer ${GITHUB_MCP_TOKEN}" }
  - name: fs
    command: reversi-connectors
    args: [serve, fs, --root, ./sandbox]       # stdio
allow: ["fs.*", "github.get_*"]               # if set, only these may be called (and listed)
deny:  ["fs.remove_dir"]
listen: { host: 127.0.0.1, port: 7431 }       # omit to speak MCP on stdio
console: { mode: off }                        # off | open | login, with role for open
resource_url: https://gateway.example.com     # public URL, for OAuth protected-resource metadata
auth:
  keys: ./keys.json
  oidc: { issuer: https://id.example.com/realm, audience: https://gateway.example.com, role_map: { bot: agent, ops: operator } }
allowed_hosts: [gateway.example.com]
allowed_origins: []

• Several upstreams are namespaced <name>.<tool> by default (namespace: false per upstream to keep names). Manifests use the exposed names. Two upstreams exposing the same name without namespacing is an error.
• ${NAME} in args, env and headers expands from the environment, so secrets stay out of the file. A stdio upstream does not inherit the gateway’s environment, only what you list.
• allow/deny globs are compiled into policy rules, so they also show up as blocked records.
• Egress check. Before connecting, every url upstream is checked against the project’s egress: rules (host allowlist, block_private, and cloud metadata addresses, which are always refused). A refused upstream stops the gateway at start with upstream <name>: <reason>. Stdio upstreams are not network destinations and are not checked.

​

Endpoints (HTTP mode)

​

Console on the gateway’s port

• open: no login, only requests addressed to a loopback host from the same origin. The gateway refuses to start if listen.host is not loopback or if the role is admin. Default role operator; --console-role picks auditor or approver.
• login: paste an API key or OIDC access token; needs auth.keys or auth.oidc.
• Rollbacks started in this console run the compensations on the upstream with the idempotency key, and verification read-backs go through the upstream too. The Connectors page lists each upstream with its health and how many tools have manifests. Manifest and policy editing works only when manifests: / policy: point at a registry or policy-versions folder (GitOps).

​

reversi.* tools

​

Storage and notifications

​

Limits