MCP

Confluye speaks the Model Context Protocol (MCP) in both directions:

• Confluye as a server: Claude Code and ChatGPT can inspect your Confluye workspace without exporting data or copying it into a prompt.
• Confluye as a client: workflows and AI agents can call tools from an external MCP server.

For a read-only session the external Confluye server exposes stable operations for workspaces, capabilities, workflows, runs, documents, knowledge bases, and tables. It also exposes non-mutating workflow planning tools: workflows.propose, catalog.search, catalog.get, workflows.validate, workflows.diff, and the documents.status lifecycle read — and publishes no mutations. A session that holds the mcp:write scope — for example a workspace API key — additionally gets typed workflow publication, debugging, document lifecycle, connection administration, and selected platform capability tools. They reuse the same registry schemas, role checks, confirmation, and idempotency rules as every other Confluye surface. Read-only clients never see or invoke those write tools, and a write tool additionally requires the signed-in user to hold a Member, Admin, or Owner role in the workspace — a Viewer is refused. Governed workflows.deploy is narrower: it is available only through a workspace API key with AIMS service_token assurance, and the key's acting user needs a current AIMS aims_manager or system_owner service-token assignment. OAuth and browser MFA do not grant MCP deployment authority.

Why connect an AI client to Confluye?

Once connected, you can ask an AI client to answer questions such as:

• Which workflows are deployed, and what do they contain?
• Which runs failed recently, and what did their logs report?
• What does our indexed workspace knowledge say about a topic?
• Which documents and tables are available for analysis?
• Is a capability ready, or does it still require setup?

The client receives live, workspace-scoped results. Confluye checks the workspace on every request, redacts secret-shaped output, rate-limits clients, and audits tool calls without storing bearer tokens.

Connect from workspace settings

The shortest path starts in Settings → API Keys → Connect MCP. Confluye already knows the active workspace, so the dialog generates its exact endpoint automatically. Choose the reach first:

• This workspace: tools act only in the current workspace. The dialog checks the workspace resource status before showing the endpoint: while that check runs it shows "Checking workspace MCP availability…"; if the check fails, "Workspace MCP availability could not be loaded." with a Retry action. When the endpoint is not yet set up, a workspace Owner or Admin sees Set up workspace MCP — MFA-protected, limited to the standard MCP scopes, and audited; other roles see the same explanation with Use a workspace API key instead, and both link to the Operator troubleshooting guide. A disabled or incompatible endpoint always shows the operator-review message with no setup commands. An active read-only endpoint (an operator-provisioned row that allows mcp:read but not mcp:write) shows a Read-only badge, and its Codex login command requests only mcp:read,offline_access.
• Whole organization: one connection (confluye-org) for the organization. When you authorize the client, the consent page asks which workspaces it may reach (all, or a selection) and whether it may write. Each tool call then names its workspaceId; workspaces.list shows the workspaces the grant covers. When the organization endpoint is not yet provisioned, the organization Owner who is also an explicit workspace Owner or Admin sees the same kind of self-service setup; other roles get the operator-review guidance. Review and revoke authorized clients under Authorized MCP clients in the same section.

Choose a client:

• Cursor: click Add to Cursor, approve the server, and complete the Confluye OAuth login.
• Claude Code: copy the generated command, run it, then open /mcp and complete OAuth.
• Codex: copy and run the two generated commands, then complete the browser login.
• ChatGPT: copy the endpoint into a custom app in developer mode, select OAuth, and scan tools.

OAuth is the default because it avoids manually distributing API keys. DCR registers supported public clients automatically, while PKCE binds the authorization code to the client that started the login. Confluye validates that the requested endpoint belongs to its public origin, names an existing workspace or organization, and is an approved, enabled resource before showing consent.

Connect Claude Code with an API key

Use this fallback for non-interactive environments or when OAuth has not been enabled for the workspace. It uses a workspace API key in an environment variable; the key is not written into a versioned .mcp.json.

1. 1

   Create and copy a workspace API key

   Open Settings → API Keys, click Create, keep the scope set to Workspace, and create the key. Use the Copy button immediately: Confluye shows the full token only once.

2. 2

   Export the token and find the workspace ID

   Export the copied token in the shell that will launch Claude Code. Then query the workspace endpoint; the UI slug, such as default, is not the workspace ID.

   export FLUXUS_HOST="https://confluye.run"
   export FLUXUS_MCP_API_KEY="<token-shown-once>"
   
   curl --fail --silent --show-error \
     --header "Authorization: Bearer ${FLUXUS_MCP_API_KEY}" \
     "${FLUXUS_HOST}/api/v1/workspaces"
   

   Copy the workspace.id value from the JSON response, then export it:

   export FLUXUS_WORKSPACE_ID="workspace-id-from-the-response"
   

3. 3

   Add the Streamable HTTP server

   Run this command from the project where you use Claude Code. All Claude options must appear before the server name.

   claude mcp add \
     --transport http \
     --scope local \
     --header 'Authorization: Bearer ${FLUXUS_MCP_API_KEY}' \
     confluye \
     "${FLUXUS_HOST}/api/v1/platform/mcp/${FLUXUS_WORKSPACE_ID}"
   

   Local scope stores the server in your private Claude configuration. The single quotes preserve the environment-variable reference instead of placing the token value in the command-generated configuration.

4. 4

   Verify the connection and call a real tool

   Start Claude Code from the same shell, run /mcp, and confirm that confluye is connected and exposing the Confluye tools. A workspace API key carries the mcp:write scope, so the list includes the typed workflow publication tools alongside the read tools. You can also inspect the configuration before starting a session:

   claude mcp get confluye
   

   Then ask Claude:

   Use Confluye capabilities.list and summarize which capabilities need setup.
   

To disconnect, run claude mcp remove confluye and revoke the key from Settings → API Keys.

Connect ChatGPT to Confluye

ChatGPT uses Confluye OAuth instead of a manually copied API key. You need a ChatGPT workspace and role that can create custom MCP apps in developer mode.

1. 1

   Create a custom app

   Enable developer mode in ChatGPT, open Settings → Apps → Create, and enter the exact Confluye MCP endpoint:

   https://confluye.run/api/v1/platform/mcp/your-workspace-id
   

2. 2

   Authorize Confluye

   Select OAuth authentication. ChatGPT discovers Confluye authorization metadata automatically. Sign in to Confluye, review the requested mcp:read permission, and click Allow read access.

3. 3

   Scan and verify tools

   Click Scan Tools. A read-only OAuth grant finds the Confluye read tools (capabilities, workflows, runs, documents, knowledge bases, and tables) and no workflow write tools. Create the app, enable it for your account, and ask the same verification question used with Claude Code:

   Use Confluye capabilities.list and summarize which capabilities need setup.
   

ChatGPT OAuth uses Authorization Code with PKCE S256, dynamic client registration, explicit consent, refresh-token rotation, and revocation. The token must belong to an active Confluye user who is a member of the workspace in the endpoint URL.

Confluye platform tools

The server advertises these stable read operations to every authorized session:

The server implements initialize, tools/list, and tools/call over Streamable HTTP using MCP protocol version 2025-06-18.

Read-only authoring tools let a client search the validated block catalog and review a candidate before any mutation. workflows.prepare-test-data accepts executionTargetId to keep fixtures in the selected preview; omitted destinations use Production. workflows.prepare-test-data, workflows.test, and workflows.execute-step appear only to write-capable sessions. Test runs simulate external writes by default; live step execution requires an explicit workflow version. See the Platform MCP reference for the complete runtime-derived inventory and rollout controls.

A session holding mcp:write also sees workflow publication tools, governed capability waves, and the Knowledge Document lifecycle. workflows.deploy appears only for an AIMS-authorized workspace API key; OAuth sessions do not discover it. Mutations take confirm: true and an idempotencyKey when their registry policy requires them, and are refused for a Viewer:

For an existing workflow, workflows.propose automatically pins the current version when expectedVersion is omitted. Send the same workflow intent to workflows.apply, either omitting the version again or passing the exact expectedVersion returned by the proposal, together with the returned planHash, confirm: true, and a stable idempotencyKey. If the workflow changes between review and apply, request a fresh proposal after the -32009 / workflow_proposal_stale response. Retrying an already successful apply with the same key and arguments replays the first result instead of creating another version.

Before MCP can deploy, a human completes the controlled AIMS workflow in Settings → AI Governance: assessment, independent approval, a dated renewal or explicit No scheduled renewal, and activation of the approved system version. An AIMS-authorized service-token key can read bounded status through aims.governance.get; the response includes a UI handoff URL but no evidence, rationale, approvals, manifests, or hashes. MCP intentionally exposes no aims.* mutations for the human-controlled steps. After activation, call the typed workflows.deploy tool with the reviewed workflow version. command.submit is an authoring and scheduling entry point, not an alternative path for governed deployment.

Configure a Confluye deployment for OAuth clients

OAuth clients require the deployment operator to set the public Confluye origin:

BETTER_AUTH_URL=https://confluye.run

Confluye accepts an exact MCP endpoint only when it uses that origin and its workspace ID exists in PostgreSQL. Token issuance additionally requires the signed-in user to remain an active workspace member. New workspaces do not require deployment-variable changes: a workspace Owner or Admin self-provisions the workspace endpoint from Connect MCP, and an organization Owner who is also an explicit workspace Owner or Admin self-provisions the organization endpoint the same way. The operator CLI below remains for disabling a resource, changing its scope policy, and non-interactive or bulk provisioning. No ChatGPT client ID or client secret is required because Confluye supports public dynamic client registration.

When self-service is not available or an operator needs to provision outside the UI, preview the change first, issue the exact capability confirmation shown by the preview, and only then apply it:

AIMS_OPERATOR_CHANGE_TICKET=CHG-124 BETTER_AUTH_URL=https://confluye.example \
  pnpm aims:operator mcp-oauth-org-resource-provision \
  --organization-id ORGANIZATION_ID \
  --workspace-id ANCHOR_WORKSPACE_ID \
  --actor-id OPERATOR_USER_ID \
  --assurance service_token \
  --allowed-scopes mcp:read,mcp:write,offline_access

The preview returns the confirmation request and plan hash. Disabled resources and existing resources with different scopes stay blocked for operator review; the settings dialog never reactivates or rewrites them.

Troubleshooting external clients

Confluye binds each authorization code and rotated refresh-token family to the workspace resource approved on the consent screen. A client cannot reuse that grant to mint a token for another workspace, even when the same user belongs to both workspaces. At the MCP endpoint, invalid OAuth claims such as the wrong audience or a missing mcp:read scope return 401; 403 is reserved for a valid credential whose user or API key cannot access the workspace in the URL.

Connect an external MCP server to a workflow

Register an external server in Settings → MCP Tools. Each connection stores an http or sse transport, endpoint URL, optional authentication headers, enabled state, and discovered tools. Streamable HTTP is preferred; SSE is supported for compatibility.

You can use a connected tool in two ways:

1. Add it to an AI agent block so the agent can call it while reasoning.
2. Add an MCP Tool node to call a specific tool directly as a workflow step.

Test an individual tool from the MCP server settings before wiring it into a workflow. The client call timeout is controlled by WORKFLOW_MCP_TIMEOUT_MS and defaults to 10 seconds.

Next steps