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

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

Related MCP server: MCPGate

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.

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.

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+

Development

npm test
npm run typecheck
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