io.github.michal-lefler/secureflows-mcp

Official18 tools

by michal-lefler · TypeScript

MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.

io.github.michal-lefler/secureflows-mcp MCP Server

This MCP server provides access to secureFlows via a token-free OpenAPI surface for AI agents. It wraps the secureFlows OpenAPI surface tagged ai-safe and ai-optional, and exposes related tools for integration-linting and token-free URL building.

🛠️ Key Features

MCP server for secureFlows
Token-free URL builders
Integration-linting tools
Wraps secureFlows OpenAPI surface tagged ai-safe and ai-optional
18 tools
Topics: ai-agents, authentication, mcp, mcp-server, model-context-protocol, secureflows, vibe-coding

🚀 Use Cases

Use by AI agents that need token-free URL construction
Perform integration linting against the secureFlows OpenAPI surface
Interoperate through Model Context Protocol (MCP)

⚡ Developer Benefits

Cloud-deployable MCP server
Standardized tool access through MCP for the secureFlows API surface

⚠️ Limitations

Public mirror published periodically; development occurs in a separate private secureFlows monorepo

Topics

ai-agentsauthenticationmcpmcp-servermodel-context-protocolsecureflowsvibe-coding

Captured live from the server via tools/list.

get_sessions

Returns the decrypted session payload for the authenticated internal session token. Response shape is a **flat JSON object**. Empty payload returns `{}`. Source: GET /api/v1/sessions Requires `auth.sessionToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Parameters5

connection	object	required
auth	object	optional
params	object	optional
query	object	optional
body	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "sessionToken": {
          "type": "string",
          "description": "secureFlows session token"
        }
      },
      "required": [
        "sessionToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {}
  },
  "required": [
    "connection"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

post_sessions

Verifies **Firebase** ID token, creates a session for **`workspaceName`**, stores serialized **`payload`** (defaults to `{}` when omitted), and returns **`sessionToken`** (JWT; subject = internal session id). Default server-side TTL is **1 hour** (implementation detail). If the Firebase token includes **`email`**, the server best-effort persists it on the workspace end-user row (for audit display). Prefer **`POST /sessions/get-or-create`** for hosted-login-style flows that should reuse an active session. Source: POST /api/v1/sessions Requires `auth.firebaseToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Parameters5

connection	object	required
auth	object	optional
params	object	optional
query	object	optional
body	object	required

Raw schema

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "firebaseToken": {
          "type": "string",
          "description": "Firebase ID token"
        }
      },
      "required": [
        "firebaseToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {
      "type": "object",
      "properties": {
        "workspaceName": {
          "type": "string",
          "description": "Workspace name to scope the session"
        },
        "app_id": {
          "anyOf": [
            {
              "type": "string",
              "description": "Optional app id (must belong to the workspace). Used for per-app session policy and auditing."
            },
            {
              "type": "null"
            }
          ]
        },
        "payload": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {},
          "description": "Arbitrary payload object stored in the session. Optional; omitted or null is stored as `{}`."
        }
      },
      "required": [
        "workspaceName"
      ]
    }
  },
  "required": [
    "connection",
    "body"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_sessions_identity

Returns the workspace end-user's **`userId`** and **email** for the authenticated session token. Does not return Firebase UID or session payload. `userId` is a stable, opaque identifier for this person across sessions and logins — it is **not** derived from Firebase. Use it as the correlation key when your own backend needs to link an external event (e.g. a billing provider webhook you receive and verify yourself) back to this user. Do not use the session token or session id for this — sessions expire and rotate, `userId` does not. Email is best-effort from hosted login (Firebase `email` claim persisted on the user row). When unknown, `email` is `null`. Browser SDK: **`secureflows-js`** **`fetchSessionIdentity(token)`** (≥ 0.1.15 for `userId`). Source: GET /api/v1/sessions/identity Requires `auth.sessionToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Parameters5

connection	object	required
auth	object	optional
params	object	optional
query	object	optional
body	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "sessionToken": {
          "type": "string",
          "description": "secureFlows session token"
        }
      },
      "required": [
        "sessionToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {}
  },
  "required": [
    "connection"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

post_sessions_get_or_create

Verifies **Firebase** ID token. If an **active** session already exists for **`(workspaceName, Firebase UID, app_id)`**, returns a new **`sessionToken`** JWT for the **most recently created** matching row (touches activity; does not create a duplicate session). The request **`payload` is ignored on reuse** — it is applied only when a new session row is created. Prefer a dedicated `app_id` per integration surface, or revoke old sessions, if you need a fresh payload. Otherwise behaves like **`POST /sessions`** (new row + default **1 hour** TTL). If the Firebase token includes **`email`**, the server best-effort persists or backfills it on the workspace end-user row (including when reusing an existing session). Intended for integrators that mirror hosted login session reuse. Source: POST /api/v1/sessions/get-or-create Requires `auth.firebaseToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Parameters5

connection	object	required
auth	object	optional
params	object	optional
query	object	optional
body	object	required

Raw schema

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "firebaseToken": {
          "type": "string",
          "description": "Firebase ID token"
        }
      },
      "required": [
        "firebaseToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {
      "type": "object",
      "properties": {
        "workspaceName": {
          "type": "string",
          "description": "Workspace name to scope the session"
        },
        "app_id": {
          "anyOf": [
            {
              "type": "string",
              "description": "Optional app id (must belong to the workspace). Used for per-app session policy and auditing."
            },
            {
              "type": "null"
            }
          ]
        },
        "payload": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {},
          "description": "Arbitrary payload object stored in the session. Optional; omitted or null is stored as `{}`."
        }
      },
      "required": [
        "workspaceName"
      ]
    }
  },
  "required": [
    "connection",
    "body"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

post_sessions_renew_session_token

Verifies **Firebase** ID token. Parses **`sessionToken`** path segment as an internal SESSION JWT **without enforcing JWT expiry** (signature and `tokenType=SESSION` are still validated). Loads the session by id from the token subject; the Firebase UID must match the session owner. Increments **`tokenRevision`** on the server so **previous session JWTs** (same session id, older revision) are no longer accepted for `GET/POST/DELETE /sessions/...`. Returns a **new `sessionToken`** (with the new `tokenRevision` claim) and the current decrypted **payload**; extends server-side session expiry by **1 hour**. If the Firebase token includes **`email`**, the server best-effort backfills it on the session owner when the user row has no email yet (audit display only). Use the path form `POST /api/v1/sessions/renew/{sessionToken}` — **URL-encode** the JWT (e.g. `encodeURIComponent` in JS). Source: POST /api/v1/sessions/renew/{sessionToken} Requires `auth.firebaseToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Parameters5

connection	object	required
auth	object	optional
params	object	required
query	object	optional
body	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "firebaseToken": {
          "type": "string",
          "description": "Firebase ID token"
        }
      },
      "required": [
        "firebaseToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {
        "sessionToken": {
          "type": "string",
          "description": "Previous SESSION JWT (may be expired); URL-encoded in the path"
        }
      },
      "required": [
        "sessionToken"
      ]
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {}
  },
  "required": [
    "connection",
    "params"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

post_sessions_set_key

Sets a key in the encrypted session payload and returns the updated decrypted payload. If the JSON body is `{ "value": <x> }`, the server unwraps it and stores `<x>` directly. Source: POST /api/v1/sessions/set/{key} Requires `auth.sessionToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Parameters5

connection	object	required
auth	object	optional
params	object	required
query	object	optional
body	any	required	JSON body can be either `{ "value": <x> }` (preferred) or a raw JSON value.

Raw schema

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "sessionToken": {
          "type": "string",
          "description": "secureFlows session token"
        }
      },
      "required": [
        "sessionToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "Payload key to set"
        }
      },
      "required": [
        "key"
      ]
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "value": {}
          },
          "required": [
            "value"
          ]
        },
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "boolean"
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        {}
      ],
      "description": "JSON body can be either `{ \"value\": <x> }` (preferred) or a raw JSON value.\n"
    }
  },
  "required": [
    "connection",
    "params",
    "body"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_sessions_get_key

Retrieves the decrypted payload value for `key`. **Important:** `404` means the key was never written (normal first-use case). Do not treat as an error. Source: GET /api/v1/sessions/get/{key} Requires `auth.sessionToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Parameters5

connection	object	required
auth	object	optional
params	object	required
query	object	optional
body	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "sessionToken": {
          "type": "string",
          "description": "secureFlows session token"
        }
      },
      "required": [
        "sessionToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "Payload key to read"
        }
      },
      "required": [
        "key"
      ]
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {}
  },
  "required": [
    "connection",
    "params"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

delete_sessions_delete_key

Removes `key` from the session payload and returns `true` if the key existed. Source: DELETE /api/v1/sessions/delete/{key} Requires `auth.sessionToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Parameters5

connection	object	required
auth	object	optional
params	object	required
query	object	optional
body	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "sessionToken": {
          "type": "string",
          "description": "secureFlows session token"
        }
      },
      "required": [
        "sessionToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "Payload key to delete"
        }
      },
      "required": [
        "key"
      ]
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {}
  },
  "required": [
    "connection",
    "params"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

post_sessions_revoke

Revokes the session referenced by the internal SESSION Bearer token. This endpoint is useful for automation clients that only hold a session token and want to revoke it cleanly. Source: POST /api/v1/sessions/revoke Requires `auth.sessionToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Parameters5

connection	object	required
auth	object	optional
params	object	optional
query	object	optional
body	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "sessionToken": {
          "type": "string",
          "description": "secureFlows session token"
        }
      },
      "required": [
        "sessionToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {}
  },
  "required": [
    "connection"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

auth_session_callback

**Browser redirect endpoint** used after hosted `/app/sessions/login`. No `Authorization` header. 1. Verifies **`firebaseToken`** (Firebase ID token). 2. Ensures **`client_redirect_uri`** is allowlisted for **`app_id`** (same rules as `validate-redirect`). 3. **Create vs renew:** If **`session_token`** is absent, **reuses the newest active session** for **`(workspace_name, Firebase UID, app_id)`** or **creates** one (`get-or-create`). Optional **`payload`** (URL-encoded JSON **object**, default `{}`) is stored **only on create** — ignored when reusing an existing session. If **`session_token`** is present (previous session JWT, may be expired), **renews** that session; **`payload`** must **not** be sent on the same request. Optional **`ttl_seconds`** applies to both paths (default **0** = unlimited; otherwise **60–604800**). When the Firebase token includes **`email`**, the server best-effort persists or backfills it on the workspace end-user row (audit display only). 4. Responds with **`302 Found`** to `client_redirect_uri` with query params **`sessionToken`** and, if provided, **`state`**. If **`client_redirect_uri`** is not allowed for **`app_id`**, responds **`400`** and does **not** redirect (open-redirect mitigation). Other failures return an HTTP error status with a JSON **`{"status", "error"}`** body and do **not** redirect. Source: GET /api/v1/auth/callback No Authorization header is required. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Parameters5

connection	object	required
auth	object	optional
params	object	optional
query	object	required
body	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {}
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {
        "firebaseToken": {
          "type": "string"
        },
        "client_redirect_uri": {
          "type": "string",
          "format": "uri"
        },
        "workspace_name": {
          "type": "string"
        },
        "app_id": {
          "type": "string"
        },
        "state": {
          "type": "string"
        },
        "ttl_seconds": {
          "description": "Session lifetime in seconds (default 0 = unlimited; allowed values: 0 or 60–604800)",
          "type": "integer",
          "minimum": 0,
          "maximum": 604800
        },
        "payload": {
          "description": "JSON object as a string (e.g. `{\"a\":1}`), URL-encoded. Must parse to a JSON object (not an array or primitive).\nDefault when omitted is `{}`. Must not be combined with `session_token` on the same request.\n",
          "type": "string"
        },
        "session_token": {
          "description": "Previous session JWT (may be expired); signature must validate. When present, the server renews this\nsession instead of creating a new one. Must not be combined with `payload` on the same request.\nURL-encode the value; very long URLs may exceed browser or proxy limits.\n",
          "type": "string"
        }
      },
      "required": [
        "firebaseToken",
        "client_redirect_uri",
        "workspace_name",
        "app_id"
      ]
    },
    "body": {}
  },
  "required": [
    "connection",
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_auth_logout

Browser-friendly logout endpoint for **cross-site** clients (e.g. apps running on `localhost`). Use this as a **top-level navigation** (not XHR/fetch) so `Clear-Site-Data` is applied in a **first-party** context on `secure-flows.com`, making cookie/session clearing reliable even when third-party cookies are blocked. **Critical client rules:** - Clear your in-app `sessionToken` state **before** navigating. - **Never** include `session_token` inside `redirect_uri` (that would silently renew and defeat logout). This endpoint (best-effort / idempotent for browser UX): - Invalidates the provided `session_token` by incrementing `tokenRevision` when the token still matches an **active** session (no new token is issued). - If the session is already expired/revoked or the revision was superseded by renew, still completes logout UX (does **not** return 401 solely for that reason). - Revokes Firebase refresh tokens for the session’s stored Firebase UID when known. - Sets `Clear-Site-Data: "cookies"`. - Redirects the browser to `redirect_uri`. Source: GET /api/v1/auth/logout No Authorization header is required. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Parameters5

connection	object	required
auth	object	optional
params	object	optional
query	object	required
body	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {}
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {
        "session_token": {
          "type": "string",
          "description": "SESSION JWT to invalidate (URL-encoded)"
        },
        "redirect_uri": {
          "type": "string",
          "format": "uri",
          "description": "Where to redirect after logout completes"
        }
      },
      "required": [
        "session_token",
        "redirect_uri"
      ]
    },
    "body": {}
  },
  "required": [
    "connection",
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

post_auth_logout

Logs out the current session **without revoking** it. **Browser warning:** calling this endpoint via XHR/fetch from a different origin than `secure-flows.com` is not a reliable way to clear hosted-login cookies. For browser apps (especially localhost), prefer the redirect helper `GET /api/v1/auth/logout?session_token=...&redirect_uri=...`. Behavior: - **Invalidates** the current `sessionToken` by incrementing `tokenRevision` (no new token is issued). - Calls Firebase `revokeRefreshTokens(firebaseUid)` using the session’s stored Firebase UID. - Sets `Clear-Site-Data: "cookies"` to clear browser cookies (including Firebase session cookie). Session payload and session row are **not** deleted or modified (other than `tokenRevision`). Source: POST /api/v1/auth/logout Requires `auth.sessionToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Parameters5

connection	object	required
auth	object	optional
params	object	optional
query	object	optional
body	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "sessionToken": {
          "type": "string",
          "description": "secureFlows session token"
        }
      },
      "required": [
        "sessionToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {}
  },
  "required": [
    "connection"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_sessions_my

Returns a page of sessions for the current user within the current workspace. Self-service dashboard endpoint — requires workspace **`enableSelfService: true`**. Payload is included only for rows whose computed status is active. Sort keys match the admin workspace session list; `pageSize` is clamped to 1–200 (default 20). Source: GET /api/v1/sessions/my Requires `auth.userToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Parameters5

connection	object	required
auth	object	optional
params	object	optional
query	object	required
body	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "userToken": {
          "type": "string",
          "description": "secureFlows USER token"
        }
      },
      "required": [
        "userToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {
        "page": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "pageSize": {
          "description": "Page size (server clamps to 1–200; 0 or invalid uses default 20).",
          "type": "integer",
          "minimum": 1,
          "maximum": 200
        },
        "q": {
          "description": "Search by session id, app id, or user identifier (own uid)",
          "type": "string"
        },
        "status": {
          "description": "Computed session lifecycle filter (`all` or same values as admin session list).",
          "type": "string",
          "enum": [
            "all",
            "active",
            "expired",
            "revoked"
          ]
        },
        "app_id": {
          "description": "Filter by client app id, or `all`.",
          "type": "string"
        },
        "sort": {
          "type": "string",
          "enum": [
            "id",
            "user",
            "app",
            "created",
            "expires",
            "status",
            "lastActivity",
            "updated"
          ]
        },
        "dir": {
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ]
        }
      }
    },
    "body": {}
  },
  "required": [
    "connection",
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

post_sessions_revoke_session_id

Self-service dashboard endpoint. Revokes a session owned by the caller in the current workspace. Requires workspace **`enableSelfService: true`**. Source: POST /api/v1/sessions/revoke/{sessionId} Requires `auth.userToken` and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Parameters5

connection	object	required
auth	object	optional
params	object	required
query	object	optional
body	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {
        "userToken": {
          "type": "string",
          "description": "secureFlows USER token"
        }
      },
      "required": [
        "userToken"
      ]
    },
    "params": {
      "type": "object",
      "properties": {
        "sessionId": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "sessionId"
      ]
    },
    "query": {
      "type": "object",
      "properties": {}
    },
    "body": {}
  },
  "required": [
    "connection",
    "params"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_docs_search

Embeds the query with Ollama (`nomic-embed-text`) and returns the closest public doc chunks from the environment's search index (pgvector). Source: GET /api/v1/docs/search No Authorization header is required. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Parameters5

connection	object	required
auth	object	optional
params	object	optional
query	object	required
body	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string",
          "format": "uri",
          "description": "secureFlows base URL, for example https://api.example.com"
        },
        "workspaceName": {
          "description": "Optional workspace name used as a default for tools that need it",
          "type": "string"
        },
        "appId": {
          "description": "Optional secureFlows app id used as a default for hosted login tools",
          "type": "string"
        }
      },
      "required": [
        "host"
      ]
    },
    "auth": {
      "type": "object",
      "properties": {}
    },
    "params": {
      "type": "object",
      "properties": {}
    },
    "query": {
      "type": "object",
      "properties": {
        "q": {
          "type": "string",
          "description": "Natural-language question or keywords"
        },
        "limit": {
          "description": "Maximum hits to return (server caps at 20)",
          "type": "integer",
          "minimum": 1,
          "maximum": 20
        }
      },
      "required": [
        "q"
      ]
    },
    "body": {}
  },
  "required": [
    "connection",
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

secureflows_build_login_url

Builds a correct hosted-login redirect URL. Needs no secureFlows token — safe to call at app-scaffolding time, before any user session exists, which is the phase most secureFlows integration mistakes happen in. Always targets /app/sessions/login (session apps). Never builds the legacy /app/login console URL, which returns a firebaseToken your SecureFlowsCallback handler cannot consume and causes an infinite redirect loop. Use this instead of hand-building the URL with URLSearchParams — hand-built login URLs are the #1 source of the login-loop and stale-renewal bugs documented in SKILL.md.

Parameters6

origin	string	optional	secureFlows origin — always https://www.secure-flows.com in production
workspaceName	string	required	Workspace name from the human prompt ("workspace = ...")
appId	string	required	App id from the human prompt ("appId = ...")
redirectUri	string	required	The app's unguarded /callback URL, built from the published/allowlisted app origin — never from an iframe or editor chrome origin.
intent	string	optional	fresh_login: normal sign-in, or app-load restore with no prior token (default — almost always correct, including after an explicit sign-out). renew_expired_token: ONLY when resuming the SAME still-intended user after a soft token expiry (401/410) while staying logged in — never after Sign out.
expiredToken	string	optional	The old sessionToken to renew. Only read when intent=renew_expired_token. Setting this after an explicit sign-out is the "send a dead JWT into hosted login" anti-pattern — it breaks renewal when the underlying identity changed.

Raw schema

{
  "type": "object",
  "properties": {
    "origin": {
      "default": "https://www.secure-flows.com",
      "description": "secureFlows origin — always https://www.secure-flows.com in production",
      "type": "string",
      "format": "uri"
    },
    "workspaceName": {
      "type": "string",
      "description": "Workspace name from the human prompt (\"workspace = ...\")"
    },
    "appId": {
      "type": "string",
      "description": "App id from the human prompt (\"appId = ...\")"
    },
    "redirectUri": {
      "type": "string",
      "format": "uri",
      "description": "The app's unguarded /callback URL, built from the published/allowlisted app origin — never from an iframe or editor chrome origin."
    },
    "intent": {
      "default": "fresh_login",
      "description": "fresh_login: normal sign-in, or app-load restore with no prior token (default — almost always correct, including after an explicit sign-out). renew_expired_token: ONLY when resuming the SAME still-intended user after a soft token expiry (401/410) while staying logged in — never after Sign out.",
      "type": "string",
      "enum": [
        "fresh_login",
        "renew_expired_token"
      ]
    },
    "expiredToken": {
      "description": "The old sessionToken to renew. Only read when intent=renew_expired_token. Setting this after an explicit sign-out is the \"send a dead JWT into hosted login\" anti-pattern — it breaks renewal when the underlying identity changed.",
      "type": "string"
    }
  },
  "required": [
    "workspaceName",
    "appId",
    "redirectUri"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

secureflows_build_logout_url

Builds a correct redirect-logout URL and refuses to build one that violates the two documented logout anti-patterns: a redirect_uri pointing at /callback (SPA callback handlers treat the tokenless return as a failed login and loop), and a redirect_uri that itself embeds session_token (silently renews the old session instead of signing out). The result always instructs top-level navigation, never fetch/XHR — cross-site fetch() to this endpoint gets a 200 but browsers silently ignore its Clear-Site-Data header on cross-site responses, so the hosted-login cookie survives and the user silently re-authenticates on the next login redirect. This tool never builds a revoke request: revoke permanently destroys the user's data and must only run on an explicit "delete my account" action, never on ordinary sign-out.

Parameters3

origin	string	optional	secureFlows origin — always https://www.secure-flows.com in production
sessionToken	string	required	The current sessionToken to invalidate.
postLogoutRedirectUri	string	required	Where the browser lands after logout completes — allowlisted, must NOT be /callback, and must NOT itself contain session_token.

Raw schema

{
  "type": "object",
  "properties": {
    "origin": {
      "default": "https://www.secure-flows.com",
      "description": "secureFlows origin — always https://www.secure-flows.com in production",
      "type": "string",
      "format": "uri"
    },
    "sessionToken": {
      "type": "string",
      "description": "The current sessionToken to invalidate."
    },
    "postLogoutRedirectUri": {
      "type": "string",
      "format": "uri",
      "description": "Where the browser lands after logout completes — allowlisted, must NOT be /callback, and must NOT itself contain session_token."
    }
  },
  "required": [
    "sessionToken",
    "postLogoutRedirectUri"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

secureflows_lint_integration

Checks source you already generated against the secureFlows integration rules. Needs no secureFlows token; safe at scaffolding time. Pass every auth/session-related file in one call — some checks are evaluated across the whole set. Two kinds of findings: • scope "file" — a forbidden construct is present (localStorage token, legacy /app/login, fetch-based logout, client-side JWT decode, empty catch, restore non-auth errors clearing session UI, Continue CTA gated on null session, ...), reported at an exact file:line. • scope "project" — REQUIRED handling is missing everywhere you passed in: detecting 401/410 but never clearing the token, never handling 403, or handling 403 without the BILLING_GRACE_LOCK carve-out. These are the defects that actually dominate real generated apps, and no "forbidden pattern" check can see them, because the bug is an absence. Heuristic text analysis, not a parser or a type checker. It can miss things it has no rule for, and a project check can be satisfied by the right keyword in the wrong place. It is a fast first pass — not a substitute for the Agent implementation checklist in SKILL.md, and specifically not for the checks that need a running app (auth-guard mount races, the fresh-reload check). Fix every "error" before calling an integration done; treat "needs_review" as a lead.

Parameters1

files

object

required

Map of relative file path -> full file source to scan, e.g. { "src/lib/secureflows.js": "..." }

Raw schema

{
  "type": "object",
  "properties": {
    "files": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      },
      "description": "Map of relative file path -> full file source to scan, e.g. { \"src/lib/secureflows.js\": \"...\" }"
    }
  },
  "required": [
    "files"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md11 KBView on GitHub

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.

Prompt (src/prompts/security-review.ts) — one MCP prompt, security-review. It asks the agent to review how the current project manages user accounts, list the security gaps, grade each one against secureFlows, and write a migration plan. Read-only, no secureFlows token required. The same text ships as the Claude Code plugin skill skills/security-review (run it with /secureflows:security-review) and as the copy-paste prompt on https://www.secure-flows.com/docs/getting-started/security-review/. The TypeScript constant is the source; test/security-review-prompt.test.ts fails if either copy drifts from it.

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):

Environment	MCP URL
Production	`https://www.secure-flows.com/mcp`
Staging	`https://secure-flows-staging.onrender.com/mcp`
Health	`…/mcp/health` → `{"ok":true}`

json

{
  "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.

Claude Code plugin

This repo is also a Claude Code plugin. It connects the hosted MCP server above (.mcp.json) and adds two skills: secureflows-integration and security-review. In Claude Code:

code

/plugin marketplace add michal-lefler/secureflows-mcp
/plugin install secureflows@secureflows-marketplace

Then run /secureflows:security-review in any project for a read-only review of its user management.

Local development (maintainers of this package)

bash

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

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).
After deploy: Playwright tests/smoke/mcp-health.spec.ts hits public GET /mcp/health and GET /mcp on the target host (production smoke job).
Local maintainer loop: npm run dev, then curl -sS http://127.0.0.1:8787/health.
Optional: MCP client against POST /mcp with connection.host + auth.* for generated tools.

Plugin distribution is covered by npm test too (offline; monorepo-only checks skip themselves in the public mirror):

test/plugin-distribution.test.ts — manifests, the hosted .mcp.json destination, the install commands on the docs pages and README, and the sync-public-mirrors CI job (tag-only, waits for the npm publishes, secrets: inherit, token only in the step env).
test/mirror-sync.test.ts — runs the real scripts/sync-public-mirrors.mjs --commit --push against a local bare git repo and checks what a stranger would receive: plugin, marketplace, skills, hosted .mcp.json, registry server.json, idempotent re-run, deletions propagate.
npm run test:live (opt-in, SECUREFLOWS_LIVE_MCP=1) — connects to the URL in .mcp.json and lists the tools; add SECUREFLOWS_LIVE_MCP_PROMPTS=1 to also require the security-review prompt. Run it after a deploy (or with SECUREFLOWS_LIVE_MCP_URL for staging). Not part of npm test, so CI stays offline.

What none of this can check: the real push with MIRRORS_PUSH_TOKEN (first run of the workflow on GitHub) and a real /plugin marketplace add from a clean Claude Code install.

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 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.

bash

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

Install

Tools (18)

get_sessionspost_sessionsget_sessions_identitypost_sessions_get_or_createpost_sessions_renew_session_tokenpost_sessions_set_keyget_sessions_get_keydelete_sessions_delete_key

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://www.secure-flows.com/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "secureflows-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.secure-flows.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

io.github.michal-lefler/secureflows-mcp MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

get_sessions

post_sessions

get_sessions_identity

post_sessions_get_or_create

post_sessions_renew_session_token

post_sessions_set_key

get_sessions_get_key

delete_sessions_delete_key

post_sessions_revoke

auth_session_callback

get_auth_logout

post_auth_logout

get_sessions_my

post_sessions_revoke_session_id

get_docs_search

secureflows_build_login_url

secureflows_build_logout_url

secureflows_lint_integration

secureFlows MCP Server

What is an MCP server?

What it does

Runtime model

For agents (the only supported client path)

Claude Code plugin

Local development (maintainers of this package)

Environment variables

Endpoints

Embedding secureFlows in an application

Testing this MCP server

Deployment

Notes

Install

Remote endpoint

Related servers