secureFlows MCP Server

Cloud-deployable MCP server that wraps the secureFlows OpenAPI surface tagged ai-safe and ai-optional.

This repo is a public mirror, published periodically from the private secureFlows monorepo where development actually happens. Issues and PRs are welcome; large changes may take a release cycle to land upstream first.

What is an MCP server?

An MCP server is a small HTTP service that exposes a set of “tools” an AI client can call in a standard way.

In this repo:

• The secureFlows MCP server exposes tools that are auto-generated from your OpenAPI YAML specs.

• When a client calls a tool, the MCP server forwards the call to your real secureFlows backend (connection.host) and returns the response in a normalized tool result.

This lets an AI client:

• discover available secureFlows operations via listTools

• call them via callTool

• without hardcoding the API surface or manual auth/header wiring

What it does

Two kinds of tools, registered together in src/server.ts:

Generated tools (src/tools/build-tools.ts) — one per OpenAPI operation:

• Loads:

  • docs/openapi/session/secure-flows-session-api.yaml

  • docs/openapi/user/secure-flows-user-api.yaml

  • docs/openapi/docs/secure-flows-docs-api.yaml

• Exposes only operations tagged ai-safe or ai-optional as MCP tools

• Forwards requests to a caller-provided secureFlows host — a thin, generic HTTP wrapper with no secureFlows-specific judgment. Every one of these requires a live auth.* token, so they're only useful once a session already exists (see Runtime model below).

• Maps secureFlows auth headers from MCP tool inputs:

  • auth.firebaseToken

  • auth.sessionToken

  • auth.userToken

Static tools (src/tools/static-tools.ts) — hand-written, not generated from the spec:

• secureflows_build_login_url / secureflows_build_logout_url — build the hosted-login and redirect-logout URLs correctly by construction (always /app/sessions/login, never the legacy /app/login; refuses a post-logout redirect_uri that points at /callback or leaks session_token). No secureFlows token required.

• secureflows_lint_integration — checks generated app source against the integration rules and reports structured findings instead of leaving them as prose the agent has to self-police. No secureFlows token required. Two kinds of finding:

  • scope: "file" — a forbidden construct is present, at an exact file:line: env-var config constants, token in localStorage, legacy /app/login, fetch/XHR logout, client-side JWT decode, revoke-on-sign-out, empty catch {}, restore setSession(null) on non-auth errors, Continue CTA gated on session === null, …

  • scope: "project" — required handling is absent across every file passed in: detecting 401/410 but never clearing the token, never handling 403, or handling 403 without the BILLING_GRACE_LOCK carve-out.

  The absence checks exist because the pattern rules structurally could not catch the defect class that dominates real generated apps. Measured: on a real trial's app that the eval harness's LLM judge scored 4/10 — citing "stale token never cleared on signed-out", "403 variants unhandled", "no error handling" — the pattern rules alone produced zero findings, because every one of those bugs is an absence, and a regex can only see what is present. With the absence checks it produces 3, including the error-severity token-clearing one. Both check kinds are validated against the canonical templates/web-app-secureflows starter, which must stay at zero findings.

  Still heuristic text analysis, not a parser or type checker: it misses what it has no rule for, a project check can be satisfied by the right keyword in the wrong place, and it cannot cover the checks that need a running app (auth-guard mount races, the fresh-reload check). A fast first pass — not a replacement for the Agent implementation checklist in SKILL.md.

These static tools exist because the generated tools can't help with the part of an integration that happens before a session exists — scaffolding the redirect/callback/token-lifecycle code — which is exactly where most secureFlows integration mistakes happen.

Uses a stateless HTTP MCP transport, so the server does not persist tenant config or secrets.

Runtime model

Each tool call receives:

• connection.host: secureFlows base URL

• connection.workspaceName: optional default workspace

• connection.appId: optional default application id

• auth.*: whichever token the selected endpoint needs

workspaceName and appId are treated as stable app config. The server injects them into known secureFlows request shapes when omitted by the caller.

For agents (the only supported client path)

Point the MCP client at the hosted URL — same host as the product, path /mcp (not a subdomain):

{
  "mcpServers": {
    "secureflows": {
      "url": "https://www.secure-flows.com/mcp"
    }
  }
}

Do not tell agents to run npx or use localhost — that splits the story and breaks anyone who never starts a local process. Wired in the web Docker image (Node on 127.0.0.1:8787, nginx location = /mcp; see docs/ROUTING.md). The Node process installs uncaughtException / unhandledRejection guards so a single bad request does not exit the process; docker/entrypoint.sh also restarts MCP if the process still exits.

Local development (maintainers of this package)

cd mcp-server
npm install
npm run build
npm test
npm run dev

The server starts on http://0.0.0.0:8787 by default (POST /mcp, GET /health). This is for changing the MCP server itself — not the path product agents should configure.

Environment variables

• PORT: HTTP port, default 8787 (in the web container, entrypoint sets PORT=8787 only for the MCP child so nginx keeps Render’s public $PORT)

• HOST: bind host, default 0.0.0.0 (web container uses 127.0.0.1)

• ALLOWED_HOSTS: optional comma-separated host allowlist for MCP host header validation

• MCP_ALLOWED_HOSTS: entrypoint override for ALLOWED_HOSTS when starting the in-image process

Endpoints

• POST /mcp: MCP Streamable HTTP endpoint

• GET /health: health check (publicly exposed as GET /mcp/health via nginx)

Embedding secureFlows in an application

Product apps integrate directly with secureFlows HTTP APIs and hosted login. Start from:

• docs/integration/quickstart.md — provisioning (workspace + application) and runtime hosted login

• docs/integration/CONCEPT.md — baseline order: login → create workspace before advanced features

• docs/openapi/integration-auth.yaml — /app/sessions/login (session apps) vs /app/login (legacy/console)

Product apps still integrate directly with the HTTP APIs above, not through this server. The generated tools here are for agents/automation that already have a token (testing, scripted verification). The static tools (secureflows_build_login_url, secureflows_build_logout_url, secureflows_lint_integration) need no token and are meant to be called by a coding agent while it's still scaffolding the integration — see What it does above.

Testing this MCP server

1. npm test in mcp-server/ — unit tests plus HTTP smoke (test/http-smoke.test.ts): starts the Express app on an ephemeral port, checks GET /health, GET /mcp → 405, and a real Streamable-HTTP client listTools + callTool(secureflows_build_login_url).

2. After deploy: Playwright tests/smoke/mcp-health.spec.ts hits public GET /mcp/health and GET /mcp on the target host (production smoke job).

3. Local maintainer loop: npm run dev, then curl -sS http://127.0.0.1:8787/health.

4. Optional: MCP client against POST /mcp with connection.host + auth.* for generated tools.

Deployment

Shipped inside the web Docker image and proxied at /mcp on www.secure-flows.com / staging (see For agents above). No separate subdomain.

The npm package secureflows-mcp-server is how CI publishes a versioned artifact (and how a standalone container can be built from mcp-server/Dockerfile); it is not the agent-facing setup path. Publish on v*.*.* tags via .github/workflows/publish-secureflows-mcp-server.yml.

docker build -f mcp-server/Dockerfile -t secureflows-mcp-server .
docker run --rm -p 8787:8787 secureflows-mcp-server

Notes

• Hosted login / redirect endpoints are exposed only if they are tagged ai-safe or ai-optional in the OpenAPI specs.

• Documentation search (get_docs_search) is ai-safe, requires no auth.* — only connection.host and query q.

• Human-only admin console APIs are intentionally excluded.

• The response payload from each tool includes:

  • status

  • ok

  • url

  • headers

  • data