MCP Server Setup¶

Overview¶

The Floh MCP (Model Context Protocol) server exposes workflow management, run control, connector operations, and configuration tools to AI assistants like Claude and Cursor. Authentication uses Authifi OIDC tokens with RBAC-controlled scopes.

Prerequisites¶

Running Floh server with OIDC configured (OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_AUDIENCE set in .env)
Authifi tenant with admin access
Node.js 18+

1. Configure Authifi Resource Server¶

Automated Setup¶

The setup script syncs Authifi with the desired Floh MCP configuration. It creates or updates the resource server, API permissions (scopes), access roles, and groups using the Authifi admin API. The script is idempotent — safe to re-run whenever permissions or roles change.

RBAC flow: User → Group → Access Role → API Permissions (scopes in token)

All access roles and groups are namespaced under floh-mcp: (e.g. floh-mcp:reader).

Obtain an admin token by logging into the Authifi admin UI and copying it from the browser DevTools (Network tab, Authorization header), or via the Authifi CLI.

AUTHIFI_BASE_URL=https://a-ci.ncats.io/_api \
AUTHIFI_TENANT_ID=<tenant-uuid> \
AUTHIFI_ADMIN_TOKEN=<your-admin-access-token> \
FLOH_AUDIENCE=http://api.floh.dev \
  node scripts/setup-authifi-resource-server.mjs

Flags: - --dry-run — show plan without applying changes - --yes — skip confirmation prompt (for CI) - --help — show usage information

The script: 1. Fetches current resource server, API permissions, access roles, and groups from Authifi 2. Computes a diff against the desired state defined in the script 3. Shows a plan of changes (creates, updates, warnings) 4. Asks for confirmation (unless --yes or --dry-run) 5. Applies only the necessary changes

What the script creates¶

Authifi Entity	Purpose
Resource Server	Represents the Floh MCP API (`FLOH_AUDIENCE`)
API Permissions	Individual scopes (e.g. `workflow:read`, `run:cancel`)
Access Roles	Permission bundles (`floh-mcp:reader`, `author`, `operator`)
Groups	User assignment targets, each linked to its access role

Manual Setup¶

If you prefer manual configuration, use the Authifi admin UI or API (docs):

Create a resource server with identifier matching OIDC_AUDIENCE (e.g. http://api.floh.dev)
Create API permissions on the resource server — see the full list in the Permission Reference section below
Create access roles tied to the resource server, each linking to a subset of permissions:
floh-mcp:reader — read-only access
floh-mcp:author — workflow authoring
floh-mcp:operator — full access including destructive operations
Create groups for each access role and link them:
PUT /groups/{groupId}/access-roles/rel/{accessRoleId}
Assign users to floh-mcp:* groups in Authifi

2. Permission Reference¶

API Permissions (Scopes)¶

Permission	Description
`workflow:read`	List and view workflow definitions
`workflow:create`	Create new workflow definitions
`workflow:update`	Update draft workflow definitions
`workflow:publish`	Publish workflows to active status
`workflow:start`	Start new workflow runs
`run:read`	List and view workflow runs
`run:update`	Retry failed runs
`run:cancel`	Cancel running workflows
`connector:read`	List and view connectors
`connector:manage`	Create, update, test, and execute connectors
`project:read`	List projects and workflow sets
`role_definition:read`	List role definitions
`user:read`	List system users
`group:read`	List user groups
`schedule:read`	List scheduled triggers
`config:export`	Export system configuration
`config:import`	Import system configuration

Access Role Bundles¶

Access roles are namespaced under floh-mcp: in Authifi. Each has a matching group for user assignment.

Access Role	Permissions
`floh-mcp:reader`	`workflow:read`, `run:read`, `connector:read`, `project:read`, `role_definition:read`, `user:read`, `group:read`, `schedule:read`
`floh-mcp:author`	Reader + `workflow:create`, `workflow:update`, `workflow:publish`, `workflow:start`, `config:export`
`floh-mcp:operator`	All permissions

Tool-to-Scope Mapping¶

Tool	Required Scope	Destructive	Requires Confirmation
`list_workflows`	`workflow:read`	no	no
`get_workflow`	`workflow:read`	no	no
`validate_workflow`	`workflow:read`	no	no
`generate_workflow_docs`	`workflow:read`	no	no
`create_workflow`	`workflow:create`	no	no
`update_workflow`	`workflow:update`	no	no
`create_version`	`workflow:create`	no	no
`publish_workflow`	`workflow:publish`	yes	yes
`start_run`	`workflow:start`	yes	yes
`list_runs`	`run:read`	no	no
`get_run`	`run:read`	no	no
`diagnose_run`	`run:read`	no	no
`retry_run`	`run:update`	no	yes
`cancel_run`	`run:cancel`	yes	yes
`import_config`	`config:import`	yes	yes
`export_config`	`config:export`	no	no
`update_connector_script`	`connector:manage`	yes	yes
`execute_connector_command`	`connector:manage`	yes	yes

3. Obtain a Refresh Token¶

The MCP server uses the user's Authifi refresh token to obtain short-lived access tokens automatically.

Method 1: Extract from Existing Floh Session¶

If you have logged in to the Floh web UI, your refresh token is stored in Redis:

redis-cli KEYS "floh:session:*"
redis-cli GET "floh:session:<session-id>"

Parse the JSON and extract the refreshToken field. If sessions are encrypted (SESSION_ENCRYPTION_KEY is set), you'll need to decrypt first.

Method 2: Authorization Code Flow¶

Request the offline_access scope during a direct OIDC authorization code flow to receive a refresh token in the token response.

Method 3: Authifi Admin Tools¶

Use Authifi admin API or UI to issue a refresh token for a user. Refer to Authifi docs for available endpoints.

4. Configure Claude Desktop¶

Build the MCP server¶

The Claude Desktop config points to the compiled dist/ output, so build first:

cd <path-to-repo>
pnpm --filter @floh/mcp build

Config file location¶

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Add the `floh` MCP server¶

Merge the following into the mcpServers object in your config file:

{
  "mcpServers": {
    "floh": {
      "command": "node",
      "args": ["<path-to-repo>/packages/mcp/dist/index.js"],
      "env": {
        "FLOH_API_URL": "https://localhost:3000",
        "OIDC_ISSUER": "https://a-ci.ncats.io/_api/auth/ls",
        "OIDC_CLIENT_ID": "floh-client",
        "OIDC_CLIENT_SECRET": "<client-secret>",
        "FLOH_REFRESH_TOKEN": "<your-refresh-token>",
        "NODE_EXTRA_CA_CERTS": "<path-to-repo>/certs/localhost.crt"
      }
    }
  }
}

Environment variables¶

Variable	Required	Description
`FLOH_API_URL`	yes	Base URL of the Floh API server
`OIDC_ISSUER`	yes	Authifi OIDC issuer URL (e.g. `https://a-ci.ncats.io/_api/auth/ls`)
`OIDC_CLIENT_ID`	yes	OIDC client ID registered in Authifi for Floh
`OIDC_CLIENT_SECRET`	no	OIDC client secret (required if the client is confidential)
`FLOH_REFRESH_TOKEN`	yes	Your personal refresh token (see Section 3)
`NODE_EXTRA_CA_CERTS`	no	Path to TLS certificate file — needed for local dev with self-signed certs

Replace <path-to-repo> with the absolute path to your Floh repository clone.

Dev fallback (static token)¶

For local development with NODE_ENV=development, you can skip OIDC and use a static floh_* API token:

{
  "mcpServers": {
    "floh": {
      "command": "node",
      "args": ["<path-to-repo>/packages/mcp/dist/index.js"],
      "env": {
        "FLOH_API_URL": "https://localhost:3000",
        "FLOH_API_TOKEN": "floh_...",
        "NODE_EXTRA_CA_CERTS": "<path-to-repo>/certs/localhost.crt"
      }
    }
  }
}

Static tokens are rejected in production — see API Tokens.

Verification¶

Restart Claude Desktop (quit fully and reopen)
Look for "floh" in the MCP server list (hammer icon in the chat input)
Try a read-only tool: ask Claude to "list my Floh workflows"
If the server fails to start, check ~/Library/Logs/Claude/mcp*.log for error details

5. Configure Cursor IDE¶

Add to .cursor/mcp.json in the workspace root:

{
  "mcpServers": {
    "floh": {
      "command": "npx",
      "args": ["tsx", "packages/mcp/src/index.ts"],
      "env": {
        "FLOH_API_URL": "https://localhost:3000",
        "OIDC_ISSUER": "https://a-ci.ncats.io/_api/auth/ls",
        "OIDC_CLIENT_ID": "floh-client",
        "OIDC_CLIENT_SECRET": "<client-secret>",
        "FLOH_REFRESH_TOKEN": "<your-refresh-token>",
        "NODE_EXTRA_CA_CERTS": "<path-to-repo>/certs/localhost.crt"
      }
    }
  }
}

6. Dev Environment Fallback¶

In development and test environments (NODE_ENV=development or NODE_ENV=test), you can use static floh_* API tokens instead of OIDC. See the "Dev fallback" subsection under Section 4 (Claude Desktop) or Section 5 (Cursor) for configuration examples.

To create a dev token, call the Floh API with an existing session:

curl -X POST https://localhost:3000/api/auth/tokens \
  -H "Authorization: Bearer <session-or-idp-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "MCP Dev", "permissions": ["workflow:read","workflow:create","run:read"], "expiresInDays": 30}'

floh_* tokens are rejected in production environments. See API Tokens for details.

7. Tool Confirmation Behavior¶

Destructive tools (publish, start, cancel, import, update connector scripts, execute commands) require explicit confirmation before execution. When called without confirmed: true, they return a preview of what will happen.

The AI assistant will present this preview to you and ask for confirmation before re-calling the tool with confirmed: true.

8. Security Notes¶

Refresh tokens are long-lived — store them securely (environment variables, secret managers). Never commit them to version control.
Token rotation: If Authifi rotates the refresh token, the MCP server stores the new one in memory automatically.
Access tokens are short-lived (typically 1 hour), cached in memory only, and refreshed automatically.
Audit trail: All MCP actions are recorded in the Floh audit log with the user's identity.
RBAC: Authifi controls which scopes appear in the access token based on the user's group/role assignments.

9. Troubleshooting¶

Error	Cause	Fix
"API tokens are only accepted in development environments"	`floh_*` token used in production	Switch to OIDC refresh token auth
"Token refresh failed: 400"	Refresh token expired or revoked	Obtain a new refresh token
"OIDC discovery failed"	`OIDC_ISSUER` URL unreachable	Check network and issuer URL
"Permission denied"	User lacks required scope	Add user to appropriate `floh-mcp:*` group in Authifi
"CONFIRMATION REQUIRED"	Destructive tool needs `confirmed: true`	Normal behavior — confirm the action