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:

Managed configuration uses the same workspace and role checks as the Tables panel. Its read tools are configuration.catalog, configuration.readRows, configuration.export, configuration.validate, configuration.preview, and configuration.history. The catalog reports database and table metadata; for an undeclared table it exposes its name and metadata only, never rows. Managed row values are returned only for explicitly declared tables, and exports are limited to selected declared tables.

A successful configuration catalog includes applyEnabled and applyDisabledReason (null or writes_disabled). These report deployment availability; they do not grant write permissions.

Write-capable sessions may also see configuration.prepare, configuration.apply, configuration.declare, and configuration.writeRow. prepare creates a proposal and returns a link to the authenticated Tables panel. MCP has no configuration.confirm tool: the human session in that panel issues the confirmation, while apply consumes the resulting confirmation and remains subject to the same workspace, Admin/Owner, drift, non-sensitive, and durable-storage checks. These tools do not expose SQL overrides or delete operations, and an agent cannot auto-approve a package. The apply, declare, and writeRow calls require both confirm: true and an idempotencyKey; the key identifies a retry and does not replace confirmation. After a lost apply response, retain the original request identity and arguments. An authorized retry can recover its committed result even if new applications have since been disabled. Exact retries of completed declarations and row writes can likewise return their stored result while new writes are disabled, subject to current authority and retained idempotency records. History receipts report the applied status.

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:

Integrations can be set up the same way. catalog.search finds a provider's blocks and credential type, credentials.create stores its secret through a workspace API key, credentials.test runs the Settings connection test, and workflows.update-target with configure-source connects a Jenkins or RSS event source to a destination. workflows.targets then reports each source's polling state. See the Platform MCP reference for their authorization rules.

When the deployment enables end users (FLUXUS_END_USERS=true), sessions with explicit workspace access also see the owner's end user tools. end_users.list, end_users.get, memory_resources.list, site_notes.list, and site_notes.get are reads; end_users.update_fact, end_users.delete_fact, end_users.erase, memory_resources.create, memory_resources.connect, memory_resources.disconnect, and memory_resources.delete require mcp:write. Reading or changing a customer's conversation, facts, or notes requires explicit workspace Admin or Owner membership, and so does memory_resources.delete, because it deletes every customer's memory in the resource. Every content read is audited. Approving a site note and creating a product gateway key are not available through MCP.

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.

Use a saved website login with Codex or Claude Code

In a Codex CLI or Claude Code node, open Playwright MCP · saved browser and select your personal browser connection. Save the node, click Authorize browser control, then save again. Confluye attaches Playwright through the node's existing MCP mechanism; your other MCP tools and instruction skills remain available. You do not need to register a separate MCP server or create a skill for each website. Once browser control is authorized, these browser tools can run unattended. This grant does not authorize tools on other MCP servers, and revoking it stops subsequent browser calls.

The agent can navigate, read a page snapshot, click, type, fill forms, select options, press keys, hover and wait. Clicking or submitting a form can change the connected account, so this permission is separate from conversational read access and existing read-only browser blocks. Cookies remain on the browser worker. Access is limited to this owner, workspace, workflow and node, and the site's allowed domains. Each run gets its own temporary browser from the saved login, which Confluye saves and closes afterwards. Other runs and agent reads can use the same connection at the same time, so avoid simultaneous changes to the same account. Revoke block access stops subsequent tool calls.

Connect and verify the website first in My browser connections. An expired website session needs login again. Code execution, cookie inspection, uploads and downloads are not exposed by this attachment. Support depends on the site's authentication and browser compatibility.

Next steps