ScopeGate

Ephemeral credentials & persistent MCP connections for coding agents — Claude Code, Kimi Code, Cursor, OpenCode.

🧩 Nexum.Work Ecosystem

This repo is one of the 4 pillars of Nexum.Work (canonical map: org/ECOSYSTEM.md).

📖 Source of truth: org/ECOSYSTEM.md

The agent never holds credentials — it holds short-lived, minimum-scope capabilities. Secrets live in an AES-256-GCM encrypted local vault and are injected only at the outbound hop. A leaked context leaks nothing of durable value.

Agent/CLI ──(MCP, zero secrets)──► ScopeGate ──(creds injected)──► GitHub / AWS / your MCPs
                                      │
                    vault + policy engine + token minter + signed audit

Capability ≠ credential. What the agent gets expires in minutes and is scoped to one task; what the vault keeps never enters the model's context.

Quickstart (agent-executable, non-interactive)

npm i -g scopegate
scopegate init

or via the installer:

curl -sSL https://scopegate.io/install.sh | sh

init is idempotent and does everything:

• creates ~/.scopegate/ (encrypted vault, master key, default policies)

• detects harness configs (Claude Code, Kimi Code, Cursor, OpenCode, .mcp.json)

• migrates existing MCPs behind the gateway, moving plaintext secrets (env vars, auth headers) into the encrypted vault and leaving only refs

• rewrites the harness config so scopegate is the single MCP entry point (backup kept as *.pre-scopegate.bak; scopegate rollback restores it)

Deposit secrets — human-only path, never through chat, never via argv:

scopegate secret add github_pat                      # hidden prompt
echo "$TOKEN" | scopegate secret add notion_token    # or piped

Then restart the agent session (once — the harness launches the gateway on startup). From there, the agent operates ScopeGate by itself through the scopegate_* MCP tools (see SKILL.md). Later secret add deposits hot-reload: the running gateway drops its connections and re-injects fresh credentials on the next call — no restart, no context loss.

CLI

Agent tools (MCP)

Exposed by scopegate start; the agent self-manages through them (21 tools).

Library API (embed the gateway in-process)

import { createGatewayServer } from "scopegate";

const gw = await createGatewayServer({ agentId: "my-worker" });
// gw.server is the full agent-facing MCP server — connect any transport.
await gw.close();

No subprocess, no daemons (opt-in), throws instead of process.exit. For consumer integration tests, scopegate/testkit ships a fake upstream and bootFakeGateway() wired to an MCP client over in-memory transport — no real credentials needed. Experimental in v0.x; strict semver from v1.

Configuration

Two files in ~/.scopegate/ (both secret-free; secrets live only in the vault):

• scopegate.yaml — upstream registry (example), transports stdio / http / openapi (OpenAPI 3 spec → one governed tool per operation, no bridge needed)

• policies.yaml — policy engine rules (example): limits (max_ttl, deny globs, rate_limit, approval_ttl), auto_approve, require: human_approval, redact: [pii], when: (argument guards — e.g. auto-approve only on kimi/* branches)

Auth types per upstream:

upstreams:
  - name: notion
    transport: { kind: http, url: "https://mcp.notion.com/mcp" }
    auth: { type: bearer, secretRef: notion_token }

  - name: github
    transport: { kind: stdio, command: npx, args: ["-y", "@modelcontextprotocol/server-github"] }
    auth:
      type: env
      env: { GITHUB_PERSONAL_ACCESS_TOKEN: github_pat }

All auth types: bearer (header injection), env (env vars into spawned stdio servers), composite (several sources fused into one stdio upstream: static refs + provider mints — multi-service MCPs 100% minted), oauth2 (refresh daemon + device-code re-auth), jwt (gateway-minted HS256), github_app (installation tokens minted from the App key), aws_sts (session credentials via AssumeRole/GetSessionToken), huly (workspace token minted via login + selectWorkspace against a Huly account service — URL discovery through /config.json), google_sa (Google service account JWT → access token), none. Minted credentials on stdio respawn proactively at 80% of their TTL, and spawned children only inherit a secret-scrubbed env (SCOPEGATE_ENV_PASSTHROUGH=1 restores legacy full-inherit). See scopegate.example.yaml for commented examples of each.

Native connectors (bridges in src/upstreams/)

Ready-to-run MCP bridges; each runs as a stdio upstream and is also available in the signed registry (scopegate_register_upstream {from_registry}):

Plus: github-official in the registry (GitHub's own remote MCP with github_app auth — ~1h installation tokens, no PAT), and the openapi transport that turns any OpenAPI 3 spec into a governed upstream.

Their manifests ship signed in registry/.

Environment variables:

Production deployment (Railway)

The gateway also speaks Streamable HTTP: scopegate start --http --port <n> --host <h> (bearer SCOPEGATE_HTTP_TOKEN on every request except a public GET /health). This repo deploys as-is to Railway:

• railway.toml pins the build (Nixpacks: npm run build) and the start command (seed-demo idempotente + start --http), with /health as the healthcheck. A root Dockerfile (multi-stage, non-root) is kept for plain Docker builds outside Railway.

• Persistent state lives on a volume mounted at /data (SCOPEGATE_HOME=/data): vault, identity, policies, config.

• With SCOPEGATE_SEED_DEMO=1 and an empty home, a clearly-marked demo seed provisions a fake upstream + fake secret so the deployment is self-contained (zero real credentials).

• Live proof: SCOPEGATE_PROD_URL=<url> SCOPEGATE_HTTP_TOKEN=<token> node e2e-prod.mjs runs the production e2e (8 assertions: health, auth 401s, initialize, listTools, grant, authenticated proxied call, diagnose, deny path).

ScopeGate Cloud (management plane)

scopegate cloud serve runs the optional multi-tenant control plane — metadata-only by design (no secret values ever cross it), and the gateway keeps enforcing its local policy + last signed team policy when the cloud is down (local-first). One process serves three things:

• GET / — the public landing page (site/)

• GET /panel — the product panel (vanilla SPA, no build step): Overview (fleet health, security events), Fleet (revocation with explicit blast-radius confirmation, including team-wide), Approvals (the human queue: approve/deny from the browser and the gateway applies it in seconds via the approval-sync loop — no terminal needed), Capabilities (live grants with TTLs), Audit (query + signed JSONL export), Policy (signed, versioned, with line diff), Billing (active-agent metering), Settings (enroll snippets, Slack alerts).

• /v1/* — the management API: enroll, signed policy distribution, audit ingest (hash-chain + per-event Ed25519 verified, looksLikeSecret guard), revocation feed, approval decisions feed, billing usage, admin overview/queue/export endpoints. GET /health is a public probe.

Gateway side: scopegate cloud enroll --cloud <url> --token <enrollToken> links a gateway to a team; from there four background loops run — policy-sync (signed, restrictive intersection), audit-export, revocation-sync and approval-sync (all fail-soft: a dead cloud never blocks a tool call).

Access today: the panel authenticates with the control plane's admin token (env ADMIN_TOKEN) — dev-grade by design; SSO with per-team roles (owner/approver/viewer) plugs into the same API via the SsoAdapter interface (src/cloud/server/sso.ts). Persistence: the FileStore (default) or PostgresStore when SCOPEGATE_CLOUD_DATABASE_URL is set — both behind the Store interface, with configurable audit retention (SCOPEGATE_CLOUD_AUDIT_RETENTION_DAYS). Verify the whole plane: node e2e-cloud.mjs (enroll → sync → central audit → panel approval loop → fleet revocation → local-first) and node e2e-landing.mjs (static routing contract).

Security model (summary)

1. Secrets never enter the model's context (CLI/stdin only, encrypted at rest).

2. Capability ≠ credential: grants expire in minutes, scoped per task.

3. Write asymmetry: agents propose policy, humans approve (policies.pending.yaml → human review).

4. looksLikeSecret() guard rejects raw secrets smuggled as refs by agents.

5. Hard limits are fail-closed: deny globs and max_ttl beat any rule.

6. Every action lands in audit.jsonl — append-only, hash-chained, signed Ed25519; inputs are hashed, never stored. Verify with scopegate audit verify.

Full detail: docs-site/security-model.md.

Telemetry (opt-in, anonymous)

ScopeGate collects nothing by default. If you explicitly opt in (SCOPEGATE_TELEMETRY=1 or {"enabled": true} in ~/.scopegate/telemetry.json), it sends a minimal anonymous event on install, init completion and first tool call: version, OS/arch, Node version, detected harness ids, a random anonymous install id. Never agentId, paths, upstream names, tool args, inputs, or anything derived from your config. Fail-silent by design — telemetry can never break a run. Endpoint: https://telemetry.scopegate.dev/v1/event (override with SCOPEGATE_TELEMETRY_ENDPOINT for self-hosting). The full payload contract lives in src/telemetry/telemetry.ts.

Documentation

• docs-site/quickstart.md — agent-executable quickstart

• docs-site/security-model.md — enforcement model

• docs-site/agent-protocol.md — the SKILL protocol

• docs-site/cli-reference.md — every command

• docs-site/configuration.md — config reference

• docs/ecosistema.md — ScopeGate in the Nexgen ecosystem (Railway map, e2e flows)

• SKILL.md — drop-in agent protocol (skills dir or CLAUDE.md/AGENTS.md)

Contributing & license

See CONTRIBUTING.md for dev setup, tests and e2e.

Licensed under Apache-2.0 (LICENSE). Deliberate choice: the gateway core is open and permissive because adoption by agents and enterprises demands zero legal friction — the future commercial moat is the cloud management plane, not the proxy. Dependency licenses (@modelcontextprotocol/sdk, commander, picomatch, yaml, @aws-sdk/client-sts) are all permissive (MIT/Apache-2.0) and compatible.