mcp-flow

One MCP endpoint for every AI harness — upstream secrets stay on the gateway.

Self-hosted workspace MCP gateway: register private and vendor MCP servers, store env/API keys encrypted, mint agent API keys, and share the same tool library across Cursor, Claude, OpenCode, OpenFlow assistants, and more. Optional central or edge runtimes run installable MCPs in a sandbox (or bare, if you opt in).

Also dual-tracked as a registry catalog for OpenFlow (one-node gallery) and ProjectEverflow (marketplace MCP tab).

PLAN.md · Campaign storyboard · Issues · Apache-2.0

Visual tour

Why it exists	Gateway architecture
Admin library	Operators

Screenshots live in docs/images/campaign-*.png. Re-shoot from docs/campaign/ with ./capture.sh.

---

Why this exists

Every IDE holding vendor API keys is not a control plane. MCP sprawl with no revoke path is not enterprise policy.

You need this when:

• Platform admins must own the tool library; employees only get a URL + agent key
• Upstream secrets must stay sealed on the gateway — never in harness config or model context
• Cursor, Claude, OpenCode, and OpenFlow should share one workspace library
• Enterprise defaults matter: deny edge-bare, no unrestricted enable-any-URL

---

Status

P1 gateway (remote proxy) implemented. Catalog sync and edge runtimes are later phases — see PLAN.md.

Issue	Topic
#1	Core plan: gateway + catalog + placement
#2	Everflow / OpenFlow catalog consumer contract
#3	Edge agent + multi-device sandbox/bare

Quickstart

Requirements: Node.js ≥ 22.

cp .env.example .env
# set MCP_FLOW_MASTER_KEY and MCP_FLOW_ADMIN_TOKEN
openssl rand -base64 32   # master key
openssl rand -hex 32      # admin token

npm install
npm run build

export $(grep -v '^#' .env | xargs)
npx mcp-flow serve --port 8787

TUI (manage upstream MCPs)

npx mcp-flow tui

Interactive terminal UI: list/add/enable/disable/test/delete backends, seal auth headers, mint/revoke agent API keys. Arrow keys + enter; q quits.

Mint an agent key

npx mcp-flow key create --name cursor
# → { "key": { "token": "mf_…", "prefix": "mf_…", … } }  # secret shown once

Add a remote MCP (headers sealed)

npx mcp-flow backend add \
  --slug deepwiki \
  --url https://mcp.deepwiki.com/mcp \
  --transport streamable-http \
  --enable

# Multiple sealed headers (repeat --header). Name=value or Name: value:
npx mcp-flow backend add \
  --slug yh-finance \
  --url https://mcp.rapidapi.com \
  --header "x-api-host: yahoo-finance15.p.rapidapi.com" \
  --header "x-api-key: YOUR_RAPIDAPI_KEY" \
  --enable

# Merge more headers later (does not wipe existing):
npx mcp-flow backend headers yh-finance \
  --header "Authorization=Bearer …"

# List header *names* only (values never printed):
npx mcp-flow backend headers yh-finance

You do not need npx mcp-remote … --header in the harness — put the URL + headers on the backend; harnesses only get the mcp-flow URL + agent key.

Point a harness at mcp-flow only

HTTP (Cursor / clients with streamable HTTP):

{
  "mcpServers": {
    "mcp-flow": {
      "url": "http://127.0.0.1:8787/mcp",
      "headers": {
        "Authorization": "Bearer mf_YOUR_AGENT_KEY"
      }
    }
  }
}

Stdio shim:

MCP_FLOW_URL=http://127.0.0.1:8787/mcp MCP_FLOW_API_KEY=mf_… npx mcp-flow stdio

Tools appear as {slug}__{tool} plus meta tools mf_list_backends, mf_list_tools, mf_status.

Docker Compose

export MCP_FLOW_MASTER_KEY=$(openssl rand -base64 32)
export MCP_FLOW_ADMIN_TOKEN=$(openssl rand -hex 32)
docker compose up --build -d

Admin REST

All /v1/* routes require Authorization: Bearer $MCP_FLOW_ADMIN_TOKEN.

Method	Path	Notes
POST	/v1/keys	Mint agent key (token once)
GET	/v1/keys	List keys (no secrets)
DELETE	/v1/keys/:id	Revoke
POST	/v1/backends	Create (GET redacts sealed headers/env)
GET	/v1/backends	List (redacted)
PATCH	/v1/backends/:id	Update / enable
POST	/v1/backends/:id/test	Upstream tools/list smoke
ALL	/mcp	Agent MCP (API key)

Security

• Upstream headers/env encrypted at rest (AES-256-GCM + MCP_FLOW_MASTER_KEY)
• Agent keys stored as SHA-256 hashes; plaintext shown once
• GET payloads never include decrypted secrets
• SSRF guards on backend URLs (MCP_FLOW_ALLOW_PRIVATE_URLS=true to allow LAN)
• Placement modes other than remote are rejected until P3+

Catalog (P1b)

npm run catalog:sync          # → catalog/entries/*.json + index.json
npx mcp-flow catalog search github
npx mcp-flow catalog show 'io.github…/name' --pretty
npx mcp-flow catalog enrich 'io.github…/name' --pretty   # README + tools/list
npx mcp-flow catalog install 'io.github…/name' --enable
# factory bulk enrich:
npm run factory:scrape -- --enqueue && npm run factory:worker

Stable allowlist id = registry server.name. Schema: catalog/schema.json (v1.0.0).
Each server is one JSON file under catalog/entries/ (plus slim index.json). See catalog/README.md.

Catalog factory TUI (queue + proxies)

Like ansible-flow-mcp’s Galaxy factory — multi-pane scrape → queue → worker, with SOCKS/HTTP proxy pool:

npm run factory:tui
# headless:
npm run factory:scrape -- --max-pages 5 --enqueue
npm run factory:worker -- --once

See scripts/factory/README.md.

Scopes + audit (P2)

npx mcp-flow key create -n intern --scope-prefix yh-finance__ --scope-prefix mf_
npx mcp-flow key scopes <id> --scope-prefix demo__
npx mcp-flow audit --limit 20
npx mcp-flow doctor

Scoped keys only see/call matching tool name prefixes (mf_status always allowed).

Development

npm test
npm run typecheck
npm run catalog:validate

# Static catalog site (campaign UI + JSON shards)
SITE_BASE= npm run site:build   # → site/out/ (+ catalog/)
npx serve site/out              # open http://localhost:3000
# Live: https://real-limitless.github.io/mcp-flow/
npm run dev   # tsx src/cli.ts serve

Architecture

AI harnesses  ──HTTP or stdio shim──►  mcp-flow /mcp  (API key)
                                            │
                    ┌───────────────────────┼───────────────────────┐
                    ▼                       ▼                       ▼
              Remote MCPs            Central sandbox           Edge agents
              (P1)                   (P3)                      (P4–P5 / #3)

License

Apache-2.0