Platform MCP

External clients call one workspace at the workspace endpoint below, or the whole organization at the organization endpoint:

POST /api/v1/platform/mcp/{workspaceId}

Product setup (OAuth, Claude Code, ChatGPT): MCP. Path and env examples may still say FLUXUS_*; those are compatibility names for the same Confluye host and token.

GET on this URL returns 405 with Allow: POST. There is no SSE GET transport.

Personal website sessions

The preview browser.list tool lists the authenticated user's personal browser connections in the selected workspace (workspaces:read). browser.read accepts { connectionId, url } and requires workflows:execute, current execution access and Allow my agent to read enabled on that connection. It reopens the saved browser, verifies the account, then returns { url, title, text, links } for an allowed HTTPS page. Website text is untrusted data. Cookies and internal browser handles are never returned. Configure the site and complete interactive login in My browser connections. The tools cannot create a login session, grant themselves permission or submit forms. Session expiry requires the owner to reconnect. Removing agent read access stops subsequent tool reads.

Auth

Bearer required. Missing token: 401 JSON-RPC -32001 Bearer token is required. plus WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource/api/v1/platform/mcp/{workspaceId}".

API key. Must verify for {workspaceId} and have a userId. A workspace key must belong to that workspace. An organization key is also accepted when {workspaceId} is inside its workspace selection and organization; its authority is capped by the key's permission and the user's current role there, and it never carries AIMS service-token assurance, so workflows.deploy, aims.governance.get and credentials.create stay unavailable to it. Wrong workspace, or a workspace outside an organization key's selection: 403 -32003 API key cannot access this workspace.; personal or copilot key: 403 -32003 A workspace API key is required. For workflows.deploy, the key supplies AIMS service_token assurance. Its acting user must also hold a current AIMS assignment for this workspace (or its organization) with role aims_manager or system_owner and requiredAssurance: service_token.

OAuth. If the bearer is not an API key, Confluye verifies an access token whose audience is the public resource URL (BETTER_AUTH_URL origin when set, else the request URL). Token workspaceId must match the path and scopes must include mcp:read. User must still be an active workspace member. Failures: 401 (unverified) or 403 -32003 (OAuth token cannot access this workspace. / Active workspace membership is required.). OAuth sessions never advertise or authorize workflows.deploy; browser MFA does not turn an OAuth grant into AIMS service-token authority. A workspace OAuth token's granted scopes are narrowed at authorize and refresh time to the resource row's allowedScopes, so a token never carries a scope outside the resource's policy — a read-only resource (mcp:read without mcp:write) yields only read-only tokens. API-key auth is unaffected: a workspace API key's authority still comes from its own scope and the acting user's workspace role.

Protected-resource metadata (GET well-known, Cache-Control: public, max-age=300):

{
  "resource": "https://host/api/v1/platform/mcp/{workspaceId}",
  "authorization_servers": ["<issuer>"],
  "scopes_supported": ["mcp:read", "offline_access"],
  "bearer_methods_supported": ["header"],
  "resource_name": "Confluye Command Center MCP"
}

Protocol

JSON-RPC 2.0. Header MCP-Protocol-Version: 2025-06-18 on responses. Server info confluye-platform 0.1.0. Max body 1 048 576 bytes (413 -32010).

Notification (no id): HTTP 202 empty body. Unknown method: -32601. Invalid JSON-RPC: 400 -32600. Parse error: 400 -32700. Invalid tool params: -32602. Capability availability: -32020. Expected missing resources use -32004; stale proposals and other expected conflicts use -32009.

Not found and pagination. A tool that reads one resource by id (workflows.get, runs.get, human-tasks.get, documents.get, knowledge.get, tables.get, catalog.get, mcp-connections.get, files.get, mailer.get, rss.get, aims.governance.get, command.status) answers -32004 with a *_not_found error.data.code when the id does not exist in the workspace; it never returns a null resource. A tool that acts on one resource by id answers the same way. List and search tools answer an empty page instead. skills.load is the exception: an unknown skill and one the principal may not use both answer -32003 skill_not_available, so existence is not disclosed. A cursor a list never issued is refused with -32602 / invalid_cursor, never treated as the first page; omit it to start over. workspaces.list for a workspace API key has a single page (the key's workspace), so any cursor is refused. The REST API and the app keep their own not-found responses. Unexpected failures remain masked as -32603 Platform MCP request failed. with only a correlationId in error.data; see Errors.

capabilities.list advertised input allows maturity: "stable" only. The runtime parse accepts preview | stable then forces maturity: "stable" before execution.

Read tools

Workflow destinations are exposed through workflows.targets and workflows.preview-target-publication. The first lists Production and named preview identities and state, plus each destination's event sources: RSS feeds, mail routes and Jenkins sources with their interval, last poll, pause and error, and per-job baseline, last build seen and skipped builds. It never returns credential secrets or the Jenkins server address. Optional includeHistory: true adds the latest 30 production deployments for rollback selection. The second requires execute authority and checks an exact workflowId, targetId, versionId, expectedRevision and UUID requestId, with optional promotion or historical activation context. A readiness result does not activate a destination or authorize a later changed request.

workflows.update-target accepts workflowId, confirm: true, an idempotencyKey, and the same change actions described in Workflow destinations. It requires write and execution authority. The publish action also requires the existing AIMS service-token and deployment authorization; an agent cannot create a human approval. Promotion carries its exact source and stop-source choice, and rollback checks the historical production snapshot again. The configure-source action adds or updates an RSS or Jenkins event source of a destination with the same checks as Versions & previews. It carries the destination's expectedRevision, and a destination whose saved version changed since that revision is refused with -32009 / workflow_target_revision_conflict without storing the source: the Jenkins connection must be one the acting user may use, job, result and interval limits apply, and a source is refused when the workflow would start a job it watches. An RSS source needs a Start trigger or a plain Webhook trigger in the destination's saved version; otherwise it is refused with event_source_trigger_not_found, because Jenkins, Sentry, app and schedule triggers only start from their own source. It does not need AIMS deployment authority. Mail and Sentry sources return a one-time secret and stay in the destination editor. Publishing a destination whose version has a Jenkins trigger fails with jenkins_source_required until its source exists.

These carry mcp:read and are advertised to every authorized session, except workflows.get and runs.get, which return full definitions and run payloads and so need secret-read or write authority: Viewers, derived organization access, and read-only organization grants do not see them. The set is derived from the runtime registry (platformMcpReadToolNames); the exact advertised inventory is verified by pnpm docs:check, so this table cannot silently drift from the server.

Managed configuration read tools are advertised with the same workspace-scoped authorization as the Tables surface:

Successful configuration.catalog responses include applyEnabled and applyDisabledReason (null when enabled, writes_disabled when the deployment flag is off). These describe deployment availability; each write still requires the caller's workspace authorization. Export reads the selected tables from one consistent database snapshot.

Write-capable sessions may see these managed configuration operations:

configuration.apply, configuration.declare, and configuration.writeRow each require both confirm: true and a nonempty idempotencyKey. An idempotency key does not count as confirmation. For configuration.apply, this envelope is additional to the human-issued plan confirmation. Repeating the same operation with the same user, workspace, key and arguments returns its stored result while the idempotency record is retained. Reusing that key with different arguments is a conflict, and current permissions are checked before a stored result is returned. If declaration or a row write reports an unknown outcome, inspect the table before attempting another write. Apply also retains its separate durable requestId receipt recovery. An authorized retry can recover a stored result for apply, declaration or a row write while new writes are disabled. This replay does not authorize a new mutation. History receipts explicitly report status: "applied". configuration.prepare declares no idempotency: each call persists a new expiring proposal, and an idempotencyKey argument is rejected with -32602.

There is deliberately no configuration.confirm tool. The authenticated human Tables panel issues the confirmation; an agent can prepare a proposal and then use the resulting confirmation only when the same user and workspace authority are still valid. Managed configuration has no SQL override or delete operation, and drift remains a blocker.

Inspecting large executions

runs.get returns run metadata, node errors, and the first ten steps and logs by default. Input/output and log metadata are omitted by default (input is null), so a large execution remains inspectable without downloading its full payload. Use nodeId to select a node's steps. This filter does not filter the run-wide logs.

Use stepOffset and logOffset independently with page.steps.nextOffset and page.logs.nextOffset. stepLimit and logLimit accept 1–10; null next offsets mean the end of that collection. Page totals describe the selected collection; the run's stepCount and logCount describe the entire execution. Offsets are best used after the execution finishes; an active execution can add or update entries between requests.

{ "workspaceId": "ws_example", "runId": "run_example", "nodeId": "codexCli_9" }

Set includePayloads: true to include input, output, and log metadata as redacted JSON text windows, each with format: "json-text", text, offset, totalChars, and nextOffset. Each window contains up to 2,048 JavaScript string characters. Request the same run/node/page with payloadOffset set to that field's nextOffset, concatenate its text windows in order, and JSON-parse only after reaching null. Offsets apply independently to every payload in the response; follow each field's own cursor. Secrets are redacted before splitting into windows. Messages and errors have bounded previews; messagePayload contains a log's full redacted message when payloads are requested. Payload omission and pagination do not mean data was lost.

Agents may monitor Human Tasks through human-tasks.list / human-tasks.get, but claiming, drafting, and completing a Human Task are human-only actions and are never advertised as tools.

Workflow authoring and debugging

Read-only clients can search the current block catalog, inspect a block's config template/schema, validate a candidate, and obtain a secret-safe diff. Debug actions require mcp:write, a current Member-or-higher role, confirm: true, and an idempotencyKey.

Integration blocks (ids starting with manifest.) carry a manifest object. In both tools it lists the operation's requiredInputs. catalog.get adds inputSchema, the JSON Schema of config.manifestInput with types, required fields, defaults and limits; credentialBinding, which names the accepted credential types and how to copy a credential's id, type and name from credentials.list into config.credentialBindings; and exampleNode, a minimal node whose <...> placeholders you replace before workflows.validate or workflows.propose. The example includes every required field: a list with a minimum length has that many items, a nested object has its required fields, and a free-form object or list item is a <field> placeholder named after its key. When the operation accepts one credential type, the example binding already has it; when it accepts several, credentialType is a <credentialType> placeholder that you fill with the type of the credential you chose in credentials.list. That binding is enough: validation, deploy checks and runs all resolve the node's credential from it, so config.credential is optional. For Jenkins: Trigger build and wait for result, jobName is required, timeoutMinutes defaults to 60 (1 to 10,080), parameters is an optional list of up to 100 { name, value } pairs, and the credential type is jenkinsApi.

Validation checks each enabled integration node's config.manifestInput against that inputSchema. A missing required field or a value out of range is an error that names the field, such as needs config.manifestInput.jobName, so the report has valid: false and the graph is not deployable. Integration tools receive only config.manifestInput; fields placed next to it in config are not sent. A {{expression}} is accepted in a field that takes text, because it is rendered to text at run time; it is refused in a number, boolean or list field. Only a complete, non-empty expression counts: an unterminated {{ or an empty {{ }} is an error that names the field, and the value is then checked like any other text. An exampleNode placeholder left in manifestInput or credentialBindings (for example <credentialName> or <credentialType>) is also an error.

workflows.diff accepts the same optional expectedVersion as workflows.apply. When it is supplied and no longer matches the workflow, the diff is refused with the same -32009 / workflow_version_conflict (with details.expectedVersion / details.currentVersion) apply would return; when it is omitted, the diff is computed against the current version. workflows.diff never returns credential values. Non-template credential fields are reported only as <configured>. workflows.execute-step rejects stale pins when the source node config changed, rejects a stop node that is not reachable from the start node, and reports the run id plus the node ids actually executed.

Typed publication lifecycle

workflows.propose is strictly non-mutating, carries the workflow read permission, and is advertised to every authorized session (mcp:read). The mutating operations — workflows.apply, workflows.update-partial, workflows.deploy, and workflows.execute — are advertised and callable only when the session holds mcp:write; read-only sessions neither see nor can invoke them. workflows.deploy is further restricted to an AIMS-authorized workspace API key and is hidden from OAuth discovery. All five reuse the canonical capability executors, so the same validation, confirmation, and idempotency rules apply on every surface.

For an existing target, callers may omit expectedVersion from workflows.propose: the server pins the current version while constructing the proposal. workflows.apply may omit it again or pass the exact expectedVersion returned by workflows.propose; both produce the reviewed normalized intent. A changed target, argument (including node position), schedule mode, or expected version reshapes the server-normalized planHash, so apply returns the actionable conflict -32009 / workflow_proposal_stale and requires a fresh workflows.propose. expectedVersion is also rechecked atomically under the workflow's advisory lock. An invalid confirmed graph returns -32602 / workflow_invalid; unexpected implementation or storage failures remain masked as -32603. validation.valid describes the graph alone, which can be saved as a draft while workspace prerequisites such as a credential or a connected integration are missing. deployable is true only when the graph is valid, missingPrerequisites is empty, the schedule mode is supported and the version matches, because deployment refuses those same prerequisites. Every tool input refuses properties its advertised schema does not list (additionalProperties: false) with -32602, so a misspelled field is reported instead of ignored. Only the mechanical workflow mode publishes through this path. Adaptive-job recurrence remains a Command scheduling feature, but command.submit is not a governed deployment path.

workflows.deploy has an additional AIMS boundary: it is advertised and callable only for a workspace API key, which supplies service_token assurance. The key's acting user must have a current aims_manager or system_owner assignment whose required assurance is also service_token. OAuth, including an MFA-authenticated browser session, cannot deploy through MCP.

The same authorized service-token principal can call the read-only aims.governance.get tool with a workflowId. It returns only the current stage, next action, active/candidate version status, bounded deployment-readiness blockers, and a URL that hands the human decision back to Settings → AI Governance. It does not expose evidence, rationales, approval records, manifests, profiles, or hashes. A saved workflow change the active governance version does not cover yet is reported as the review_required blocker; the same next action on an already-current workflow is only the standing governance-only change opportunity and is not reported as a blocker.

If the AIMS assignment lookup itself fails, only the AIMS capabilities fail closed: workflows.deploy and aims.governance.get are neither advertised nor callable and return -32003, while every unrelated MCP tool in the session keeps working. The server emits a sanitized operational signal naming the surface, workspace, and client; no database or error detail reaches the client or the log line.

MCP does not create or approve AIMS assessments, choose a renewal policy, or activate an AIMS system version. A human completes those controlled steps in Settings → AI Governance, including independent approval and either a dated renewal or No scheduled renewal. Once that version is active and its authoritative production manifest is current, the service-token principal may call workflows.deploy. Do not submit a natural-language deploy request through command.submit; it does not replace the typed, governed deploy operation.

workflows.update-partial

Unlike apply, update-partial needs no separate propose call: it takes workflowId, an ordered operations array, an optional expectedVersion (defaults to the workflow's current version when omitted), idempotencyKey, and confirm: true, and applies the whole batch atomically against the workflow's current candidate graph in one call. Either every operation in the array applies and the resulting graph passes validation, or nothing is persisted. A schema-invalid or runtime-failing operation returns workflow_update_partial_operation_failed and names the failing operation's index and declared op; a final whole-batch validation failure returns workflow_invalid with the graph validation reason, without attributing it to a single operation. addNode accepts an optional caller-supplied nodeId, which lets later operations in the same batch address the new node; the ID must be unique in the workflow. addNode connects the new node automatically unless it passes autoConnect: false: a trigger is wired to the first step, and any other node is inserted before the Output node (replacing the edge into it) or appended after the last step. Pass autoConnect: false when the batch wires the node with its own addEdge operations. addEdge likewise accepts an optional caller-supplied edgeId (same format as a node id, unique in the workflow; a duplicate fails that operation), so a later setEdgeLabel or removeEdge in the same batch can address the new edge. The result carries version, planHash, applied (one { op, summary, warnings } entry per operation, with the resolved nodeId on addNode and the resolved edgeId on addEdge), and the same diff / validation shapes workflows.propose / workflows.apply already publish. workflows.update-partial only ever writes name, description, nodes, and edges on the workflow's draft — it never promotes a workflow to production; workflows.deploy remains the only path that activates a version.

MCP tool discovery advertises the full typed operation union. At tools/call time, operation validation is deferred to the canonical executor so malformed entries receive the same indexed domain error as direct executor callers instead of a generic boundary-schema error.

update-partial rejects with the same actionable conflict -32009 / workflow_collaboration_session_active when a live-collaboration session is already active on the workflow, so a human editing the graph in the canvas and a typed caller never race each other's edits.

The mergeNodeConfig operation deep-merges its patch object into the target node's existing config using JSON Merge Patch (RFC 7396) semantics, with one deliberate deviation: an array-valued field merges by index, so the patch array's value at index i overwrites the existing array's value at index i, preserving any existing tail beyond the patch's length, rather than replacing the array wholesale. A null value at a key deletes that key. A patch that touches a managed integration key (credential bindings or manifest fields) is rejected — use the workflow's existing integration-config path for those instead. Before recursive schema parsing, the operation input is limited to 16 nesting levels, 1,000 object keys, 100 values in any array, 5,000 decoded values, and 65,536 decoded JSON bytes. Exceeding a limit returns workflow_update_partial_operations_invalid without evaluating or persisting the patch.

workflows.get returns executionState with candidateVersionId, activeVersionId, reviewStatus, synchronizedVersionId, and reviewReady. workflows.execute defaults to the active production version. Pass target: "candidate" to test the candidate; it defaults to dry run. A live candidate execution additionally requires dryRun: false and the matching expectedVersionId. Without both, it returns -32602 with live_candidate_confirmation_required. A stale expectedVersionId returns -32009 with workflow_version_changed and names the current version, and running active before any deploy returns -32009 with workflow_not_deployed. The result carries requestedTarget, versionId, resourceMode, and reviewIdentity, matching the run evidence shown to humans. Candidate and active are not isolated runtimes: a live candidate uses real workspace resources, and active v1 remains production until an explicit deploy promotes v2.

Knowledge Document lifecycle

documents.status reads an owned document's current indexing generation, indexing status, and knowledge-base links; it is non-mutating and advertised to every authorized session (mcp:read). The lifecycle mutations are advertised and callable only with mcp:write. Every operation reuses the canonical capability executor, so document/knowledge-base ACLs, the generation-aware CAS, and idempotent replay behave identically on MCP, the API, the Agent Runtime, and the knowledgeDocument workflow node.

Each mutation carries the same envelope as the publication lifecycle: confirm: true plus an idempotencyKey (missing either is -32602 with zero executor dispatch). Pass the document's current expectedIndexingGeneration to bind the mutation to the state you read from documents.status; a losing compare-and-set fails closed without mutating. Repeating a mutation with the same key and arguments returns the original result without a second write or generation, marked deduplicated: true (top-level for documents.create and documents.edit, in result for the lifecycle operations); reusing the key with different arguments, including a different expectedIndexingGeneration, is an idempotency_key_mismatch conflict (-32009). A missing document or knowledge base is -32004, and a generation or state conflict is -32009. Claiming, drafting, and completing a Human Task remain human-only and are never advertised here.

Workspace management

workspaces.rename changes only the workspace display name. The slug, route key, URLs, id, membership, and visibility are unchanged, so every integration, API key, agent card, and bookmarked URL keeps working. It reuses the canonical capability executor and the same audited domain service the Settings UI, tRPC, and REST rename share, so authorization and audit are identical on every surface.

The mutation carries the same envelope as the other lifecycles: confirm: true plus an idempotencyKey (missing either is -32602 with zero executor dispatch; a repeated key replays the recorded result rather than renaming twice). On the organization endpoint it is a workspace-bound tool: the call must name its workspaceId, which is re-authorized against the caller's live membership and the grant's workspace ceiling before it runs. There is no organization-global rename.

Workspace role authorization

An OAuth or API-key scope states what the client was granted; it says nothing about what the acting user may do. Every mutating tool therefore also passes the shared workspace role/permission matrix against the principal's current membership: workflows.apply, workflows.update-partial, workflows.deploy, workflows.execute, and the documents.* lifecycle require Member, Admin, or Owner; workspaces.rename requires Admin or Owner (an explicit workspace-admin action). A Viewer (or a principal with no current membership) is refused with 403-class -32003 (MCP tool <name> requires a workspace role that can write. / … can admin. / … can execute.) before any executor call. Read tools, workflows.propose, and documents.status need membership only, except the full-projection reads (workflows.get, runs.get, workflows.preview-target-publication, credentials.list, credentials.test), which need secret-read or write authority.

tools/list advertises only the tools the session can call: a tool whose role check the principal's current capabilities cannot pass is hidden, as is credentials.create for any session other than a service-token workspace API key. A role change after tools/list is still enforced by the call-time check.

That workspace role is separate from AIMS authorization. workflows.deploy additionally requires the workspace API key posture and a current AIMS aims_manager or system_owner service-token assignment; the deployment gate rechecks that assignment at execution time.

Governed capability waves

The following preview operations are selected from the canonical capability registry. They are visible only to write-capable MCP sessions while FLUXUS_MCP_CAPABILITY_WAVES is enabled. Registry schemas, workspace roles, confirmation, idempotency, egress controls, and the canonical executor remain authoritative.

runs.rerun takes runId, confirm: true, and an idempotencyKey, and repeats the original run with its input, target, and pinned version. A live-candidate run is rerun live against the same candidate version, also while the workflow has never been deployed; a dry run is rerun as a dry run. To test a newer candidate, call workflows.execute with its expectedVersionId instead.

Connection administration returns endpoint metadata, credential-reference names, status, and discovered tool schemas; it never returns resolved headers or secret values. The endpoint is shown in a readable redacted form: only the scheme, host and port are kept. User info and the fragment are dropped, any non-empty path becomes a single literal /<redacted> (a secret can equal any path word, api or mcp included), and a non-empty query, parameter names included, becomes a single ?<redacted>, for example https://mcp.example.com/<redacted>?<redacted>. The stored endpoint is unchanged. Creating a connection accepts only header templates such as Bearer {{credential.remote_api_key}}. Consent and credential exchange remain human UI actions.

mcp-connections.create and mcp-connections.update apply the outbound network policy before they store an endpoint, the same policy web.read and the MCP client enforce: a private, loopback, link-local, cloud metadata (169.254.169.254), or internal host, or a name that resolves to one, is refused with -32602 / egress_blocked and nothing is saved. A credential template in the user info, port, path or query does not skip this check: the concrete host is still validated. Only a host chosen by a template is left to the runtime guard, which checks it on every call; its scheme must still be http or https. An endpoint that is not a valid absolute URL, including a relative path such as /api/v1/..., a value without a scheme, and an unterminated or unsupported {{ ... }} in the host, user info or port, is refused with -32602 / mcp_endpoint_invalid; it is never resolved against the platform's own origin. The REST and Settings paths share this check. An operator can opt a legitimate private installation back in with FLUXUS_HTTP_EGRESS_ALLOWLIST.

mcp-connections.test, mcp-connections.refresh, mcp-connections.configure-tool, and mcp-connections.delete answer an unknown connection with -32004 / mcp_connection_not_found. Repeating a completed delete with the same idempotencyKey returns its original { deleted: true, deduplicated: true } receipt; a new key for a connection that no longer exists is -32004. Testing or refreshing a disabled connection is -32009 / mcp_connection_disabled, a header template whose credential is not stored is -32009 / mcp_credential_missing, and configuring a tool outside the current discovery snapshot is -32004 / mcp_tool_not_found.

runs.cancel cancels a queued, running, or waiting run. A run that already finished is -32009 / run_not_cancellable; a replay of a completed cancel with the same key returns its original receipt.

Credential tools serve any integration provider whose manifest declares a credential type, such as Jenkins (jenkinsApi). credentials.list returns metadata only (id, name, type, scope, creation time and the providerIds each credential serves) and accepts an optional providerId filter. credentials.create takes providerId, name, the secret value, optional credentialType (needed only when a provider declares several), scope (workspace or personal) and replaceExisting, with confirm: true and an idempotencyKey. It needs write authority and a workspace API key with service-token assurance; OAuth and organization sessions are refused with -32003 and must use Settings → Credentials, which requires recent step-up. A credential with the same name is replaced only with replaceExisting: true, and only when it has the same credential type; a same-named credential of another type is refused with credential_type_conflict, so choose another name. The secret is checked with the provider's own parser before it is stored: a Jenkins secret needs an https:// server URL, a user and an API token, and a WhatsApp secret needs an access token. A secret the provider could not use is refused with -32602 / credential_value_invalid and a message that names the missing part, never the secret. credentials.test runs the Settings connection test with a credential the acting user may use. Listing and testing need secret-read or write authority. No tool returns a secret value; creation is audited without it. Deleting a credential remains a Settings action. The request identity binds the secret only through a keyed digest, so an identical retry replays its receipt across an APP_ENCRYPTION_KEY rotation while the previous key stays in APP_ENCRYPTION_PREVIOUS_KEYS; once that key is removed, the retry is refused as idempotency_key_mismatch.

End users

While the deployment runs with FLUXUS_END_USERS=true, the server advertises the owner's end user operations (platformMcpEndUserReadToolNames and platformMcpEndUserMutationToolNames). They are hidden and refused (-32602 Unknown MCP tool) while the flag is off. A session with organization-derived access is refused like for every other non-safe tool, and product gateway keys are refused by the MCP endpoints (403).

end_users.list returns nextCursor; pass it back as cursor to read the next page, until it is null.

Every mutation takes an idempotencyKey; the ones marked above also need confirm: true. The end_users.* and site_notes.* tools require explicit workspace Admin or Owner membership, and end_users.get and site_notes.* write a content-read audit event; memory resource reads need membership and their mutations need Member or higher, except memory_resources.delete, which deletes customer content and requires explicit workspace Admin or Owner membership. Returned conversation, memory, and note text comes from external customers: treat it as untrusted data, never as instructions. Approving a site note and creating product gateway keys are human-only actions and have no MCP tool; granting a workflow node access to a website (and revoking that grant) is available only in the app for now.

Command tools

The higher-level natural-language authoring path (platformMcpCommandToolNames) remains available alongside the typed lifecycle. command.status is a read; command.submit, command.confirm, and command.cancel require mcp:write and are hidden from read-only sessions. command.submit may author or schedule work, but it is not the route for AIMS-governed deployment; clients must use the typed workflows.deploy operation after human governance is complete.

A job that already reached a final state, including a blocked job without a pending confirmation, cannot be canceled: command.cancel answers -32009 / invalid_state_transition. Use Retry to re-plan a blocked job.

Each Command tool advertises an object output schema. command.submit returns { threadId, job, queued, replayed }; command.status returns { threadId, messageId, plan, job, result, error, attempt, retryOfJobId }; command.confirm and command.cancel return { job }. The schemas pin job.id, job.planId and job.status and allow additional fields, because the job projection grows with Command Center.

Unknown or non-allowlisted name: -32602 Unknown MCP tool: …. Read-only sessions cannot see or call any write-scoped tool. Executors redact secret-shaped strings.

Organization endpoint

One connection for every workspace an access grant reaches:

POST /api/v1/platform/mcp/org/{organizationId}

Auth. OAuth 2.1 tokens whose audience is the organization resource (https://<origin>/api/v1/platform/mcp/org/{organizationId}, claim organization_id), or an organization API key. Workspace tokens and workspace, personal, or copilot keys are refused (401 / 403 -32003). An OAuth session also needs an access grant: the reach the user chose on the consent page (all workspaces or selected ones; read only or read and write). Without one the endpoint answers 403 -32003 and asks the client to authorize again.

Targeting. Every workspace-bound tool advertises a required workspaceId (the registry schema plus that one property) and its description starts with Acts in the workspace identified by workspaceId. workspaces.list and capabilities.list take none; workspaces.list returns only the workspaces the grant reaches. billing-usage.organization keeps its own workspaceId, which is both the target and the filter.

Per-call authorization. The target must be inside the grant and inside the organization, the user must currently hold access there, and the effective authority is token scopes ∩ grant permission ∩ the user's live role and capabilities. A workspace outside the grant, outside the organization, unknown, or where membership was lost returns one message: Workspace is not available to this connection. Call workspaces.list to discover the workspace ids this connection may use. (-32003). A missing workspaceId returns -32602 naming the tool. AIMS-gated tools (workflows.deploy, aims.governance.get) are never advertised here.

tools/list is the union the scopes and grant permission allow; each call is still authorized for its target. Read-only grants hide write tools and the full-projection reads (workflows.get, runs.get, workflows.preview-target-publication, credentials.list), because a read grant never carries secret-read authority in any workspace. credentials.create is never advertised here. Audit events carry the target workspace and metadata.surface: "organization". The user rate-limit key is org:{organizationId}:{userId}. Rollout flag: FLUXUS_MCP_ORGANIZATION_HUB.

Rate limits

Three sliding windows, 120 / 60s each:

Exceeded: 429 -32029 MCP rate limit exceeded. IP is checked before auth.

Audit and idempotency

Each tools/call writes platform.mcp.call (no bearer stored). Audit failure does not fail the RPC. Read tools, workflows.propose, and documents.status take no Idempotency-Key; the write-scoped workflows.apply, workflows.update-partial, workflows.deploy, workflows.execute, and documents.* lifecycle tools require an idempotencyKey argument, so one key retried returns the first draft, partial-update version, deployment, run, or document mutation rather than creating a second. Deploy audit events are attributed to the authenticated external principal.

Errors (HTTP + JSON-RPC)

Expected workflow publication failures return -32004 for workflow_not_found or -32009 for a blocked/conflicting publication. Their safe error.data contains code, retryable, and, for an AIMS block, the bounded blockers list. Arbitrary diagnostic details are not returned.

Other expected failures return the same error.data shape (code, retryable, and sometimes details or blockers):

command.confirm answers confirmation_not_found when the job exists but has no pending confirmation with that id, and Confluye Command job was not found. only when the job itself is unknown.

A masked -32603 carries error.data.correlationId. The server logs the same id with the tool name, the error class, a fixed-length hash of the message for grouping repeats, and the file:line of the originating stack frame. The message text itself is never logged, because it can quote credentials or provider responses. The hash is keyed with a secret derived from the server's encryption key, so someone who can read the logs cannot confirm a guessed message or credential against it; without a configured encryption key the hash is omitted.

Gaps

• GET/SSE not implemented (405).
• tools/list does not emit listChanged notifications.
• capabilities.list schema vs runtime maturity differ (preview is accepted then overwritten).
• Rate limiters are in-process (not shared across instances).
• Read tools and the read-only workflows.propose / documents.status are available to every authorized session; the typed workflows.apply, workflows.update-partial, workflows.execute, and documents.* lifecycle mutations require mcp:write and a Member-or-higher workspace role. workflows.deploy additionally requires a workspace API key and a current AIMS service-token aims_manager or system_owner assignment. The per-workflow MCP servers remain a different surface (/api/v1/workflows/mcp/...).

Next steps