Fluency MCP

Use the Fluency MCP (Model Context Protocol) server to let an AI client read your organization’s Observe data: processes, opportunities, artifacts, software, teams, and users. The client signs in with WorkOS AuthKit, the same identity provider as the Fluency app. Fluency does not issue a separate MCP API key. The server is read-only. It cannot create, update, or delete anything in Fluency.

Regional endpoints

Your organization’s data lives in one Fluency region. Use the MCP URL for that region. A token issued for the other region is rejected. You will see If you are unsure which region your organization uses, sign in to Fluency as usual. Your Fluency admin or Fluency support can confirm the home region. Do not send the other region’s URL: org data does not cross regions.

Who can call which tools

Access follows your Fluency organization role. Fluency reconciles that role with live WorkOS membership on every request, so a removed or demoted user loses MCP access without waiting for the token to expire.

Role	What they can read
Admin	The full catalog below, including Observe processes, opportunities, artifacts, and software
Reviewer	The same Observe catalog as admin

Connect a client

MCP clients discover AuthKit from the MCP URL. You do not paste a client id, client secret, or Fluency API key. On first use the client opens AuthKit; you sign in and consent to the organization you want the client to read.

Cursor

Open Cursor Settings → MCP.
Add a new server with transport HTTP (sometimes labeled Streamable HTTP).
Set the URL to your regional endpoint, for example https://api.usefluency.com/mcp.
Save. Cursor fetches Fluency’s protected-resource metadata, registers itself with AuthKit, and prompts you to sign in.
Complete AuthKit sign-in and organization consent in the browser window Cursor opens.
Confirm the server lists Fluency tools such as process_list and opportunity_list.

A mcp.json entry looks like:

{
  "mcpServers": {
    "fluency": {
      "url": "https://api.usefluency.com/mcp"
    }
  }
}

Use the US URL instead if that is your home region.

Claude

In Claude Desktop or Claude.ai connectors, add a custom MCP server and paste the same regional URL. Claude runs the OAuth discovery flow against AuthKit. Sign in as a Fluency user in the organization you want to query.

ChatGPT and other MCP hosts

Any client that implements MCP Streamable HTTP and OAuth 2.1 (RFC 9728 protected-resource metadata) can connect the same way: give it the regional /mcp URL, complete AuthKit consent, then call tools. Fluency advertises:

Resource: https://<regional-api-host>/mcp
Authorization server: your AuthKit domain
Bearer tokens in the Authorization header only

What the tools return

Every tool is scoped to the organization you consented. You cannot pass another organization’s id; the server ignores org ids in tool arguments.

Tool	Returns
`process_list`	Paginated process summaries (name, group, category, teams, run counts). Optional `search`.
`process_get`	One process: activities, actions (the token graph), execution summary, attached opportunity.
`activity_get`	One activity of a process: actions, observed paths, execution summary.
`process_executions`	Recent executions of a process (or of one activity), most recent first.
`opportunity_list`	Automation opportunities with feasibility, value, and quadrant. Optional `search` and `quadrant`.
`opportunity_get`	One opportunity: valuation, feasibility, per-step verdicts, rearchitected TO-BE map.
`opportunity_stats`	Aggregate opportunity counts and mix for the org.
`artifact_list`	Observe artifacts (named work items Fluency saw being handled — invoices, tickets, cases — not workflow files). Requires the `artifacts` flag.
`artifact_get`	One artifact: value, processes that handled it, people on those runs. Requires the `artifacts` flag.
`software_list`	Software applications observed in captured work (canonical software tags). Optional `search`.
`software_get`	One application: usage, aliases, processes and activities that use it.
`team_list`	Teams. Callers with org-wide team read see every team; others see only teams they belong to.
`team_get`	One team: name, description, member count. Same membership scoping as `team_list`.
`user_list`	Org members as id, email, and name.
`user_get`	One org member by WorkOS user id.

List tools are paginated. Defaults are conservative (typically 10 items; process executions default to 20, max 50). Prefer *_list then *_get with a stable id from the list. Software in MCP is Fluency Applications (the software catalog). Artifacts are Observe artifacts, not business-artifact or workflow-telemetry files.

Authentication details

Sign-in is WorkOS AuthKit with OAuth 2.1. The MCP client is a third-party OAuth application; AuthKit shows a consent screen the first time you authorize it for an organization.
Fluency product session cookies and dashboard JWTs are not accepted on /mcp. You must complete the MCP OAuth flow even if you are already signed in to app.usefluency.com.
Internal Fluency machine tokens are a separate, Fluency-operated path. Customers do not mint those.
Tokens are bound to one organization (org_id) and, for user sign-in, to one region (organisation_region). Switching organization in AuthKit issues a different token.
If your Fluency role changes, the next MCP request asks you to re-authenticate. Reconnect the client rather than retrying with the old token.

Limits and behaviour

Read-only. There is no write, delete, export-download, or settings tool.
No Settings UI in Fluency for MCP. Adding the URL in the client is the entire setup.
Tenant isolation. The organization on the token is the only tenant the tools can read.
Rate limits. /mcp uses the same API rate limits as other Fluency HTTPS routes. Back off on HTTP 429.
Errors. Failed tool calls return a generic tool error to the model. They do not include database connection strings or upstream stack traces.

Troubleshooting

What you see	What to do
HTTP 401 with `WWW-Authenticate` and `resource_metadata`	The client has not completed OAuth, or the token is expired. Reconnect and sign in through AuthKit.
HTTP 403 mentioning another region’s MCP URL	You used the wrong regional endpoint. Switch the client URL to the one in the error.
HTTP 403 `This MCP endpoint requires an organisation_region claim`	The token is not a Fluency Connect user token for this MCP resource. Re-run the client’s OAuth flow against the regional `/mcp` URL.
`User role has changed. Please re-authenticate.`	Your WorkOS role no longer matches the token. Sign in again.
`Insufficient role` on `process_`, `opportunity_`, `software_`, or `artifact_`	Your live role is member. Ask an admin to grant reviewer or admin if you need Observe data.
`Artifacts feature is not enabled`	Your user does not have the `artifacts` flag. Enable it in WorkOS, refresh the Fluency session, reconnect MCP.
Client never starts OAuth	Confirm the URL ends in `/mcp` (no trailing path), uses `https`, and matches your region. Fluency publishes `/.well-known/oauth-protected-resource` on the same API host.

Privacy

Tool results include the same class of data you can already see in Fluency for your role: process structure, opportunity scores, artifact values, software names, team names, and member emails. Do not paste those results into tools or prompts outside your organization’s policy. Fluency does not send your org’s data to the MCP host except as the tool result of a call you (or the signed-in user) authorized.

Getting Started

IT Setup

Admin Setup

Work Explorer

Opportunities

SDKs

MCP

Product Updates

Regional endpoints

Who can call which tools

Connect a client

Cursor

Claude

ChatGPT and other MCP hosts

What the tools return

Authentication details

Limits and behaviour

Troubleshooting

Privacy

​Regional endpoints

​Who can call which tools

​Connect a client

​Cursor

​Claude

​ChatGPT and other MCP hosts

​What the tools return

​Authentication details

​Limits and behaviour

​Troubleshooting

​Privacy

Regional endpoints

Who can call which tools

Connect a client

Cursor

Claude

ChatGPT and other MCP hosts

What the tools return

Authentication details

Limits and behaviour

Troubleshooting

Privacy