> ## Documentation Index > Fetch the complete documentation index at: https://docs.usefluency.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 1. Open Cursor Settings → MCP. 2. Add a new server with transport **HTTP** (sometimes labeled Streamable HTTP). 3. Set the URL to your regional endpoint, for example `https://api.usefluency.com/mcp`. 4. Save. Cursor fetches Fluency's protected-resource metadata, registers itself with AuthKit, and prompts you to sign in. 5. Complete AuthKit sign-in and organization consent in the browser window Cursor opens. 6. Confirm the server lists Fluency tools such as `process_list` and `opportunity_list`. A `mcp.json` entry looks like: ```json theme={"system"} { "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:///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.