Skip to Content
MCP / AIAuthentication

MCP — Authentication

For a connection that works today, use the exact snippet on your tenant’s Settings → MCP page in the FlowState app, rather than hand-typing OAuth configuration on the client-setup pages.

How authentication works

FlowState’s MCP server uses Cognito OAuth to authenticate users. The flow is intended to be identical to the web UI login — the same Cognito user pool, the same identity, the same permissions. The MCP server never issues its own tokens.

The MCP server validates the Cognito access token on every tool call, extracts the tenant_id claim from the JWT, and scopes the operation to that tenant. No tool call requires a tenant_id parameter.

PKCE authorization flow

  1. Your LLM client (Claude Desktop, Claude Code, etc.) initiates the auth flow by opening the Cognito authorization URL in your default browser.
  2. You sign in on the Cognito hosted UI with your email and password, or with Google SSO.
  3. Cognito redirects back to a registered callback URL with an authorization code.
  4. The code is exchanged for an access token and refresh token.
  5. The access token is included in every tool call to the MCP server as a Bearer token in the Authorization header.

Token lifecycle

TokenLifetimeNotes
Access token60 minutesValidated on every tool call. Short-lived to limit exposure.
Refresh token30 days (sliding)Used to issue a new access token without re-authentication.

When the access token expires, a fresh one is obtained using the refresh token automatically, where the client supports it. If the refresh token expires (30 days of inactivity), re-authentication is required.

Tenant selection

select_active_tenant does not re-issue a token. It always returns {"error": "NOT_SUPPORTED", ...} directing you to the web UI, and its parameter is target_tenant_id, not tenant_id. To work in a specific tenant’s context, switch tenants in the FlowState web app first — your next MCP session picks up the tenant scoped into your token there.

You can check your current active tenant and available tenants with list_my_tenants() and get_my_profile().

Security notes

  • The MCP server validates the JWT signature using Cognito’s JWKS endpoint, with keys cached for up to 1 hour.
  • The token_use claim must be access — ID tokens are rejected.
  • The client_id claim must match an allowlisted app client — tokens from other Cognito app clients are rejected.
  • The MCP server never accepts tenant context from request parameters or headers — only from the JWT tenant_id claim.
  • Token revocation: for privileged MCP tool calls, the server performs a live Cognito GetUser check to verify the token has not been revoked since issuance.
OverviewTool catalog