Platform MCP (in design)
How AI agents will operate BPMS.ai through MCP tools. In design, not available yet.
In design
This page describes the design of the BPMS.ai platform MCP server. It is not available yet: the current version of BPMS exposes no MCP tools. The design may change as it is built, and this page is updated with it.
The platform MCP server will let AI agents operate BPMS.ai with the same rules as any other client: the same permissions, the same tenant isolation, and the same audit log. It is separate from the docs for agents, which only read this documentation and are available today.
Tools
Every tool declares:
- Its toolset, the group it belongs to.
- Its mandatory permissions. A tool without declared permissions stops the server from starting.
- Its behavior: read-only, mutating, or destructive. A destructive tool asks for confirmation.
- Its input and output schemas.
Each tool runs with a real request context, the tenant and the caller of the session, and every call is recorded in the audit log.
Agent access
An agent connects under the mcp/ protocol root with an MCP access token: a token a user creates, bound to the mcp/ protocol, with a subset of that user's permissions, sent as a bearer token. A session opened for another protocol, such as the REST API, is not accepted there. The dashboard, the CLI, and MCP agents share one permission model and one audit log.
Long-running operations
Some work grows with the tenant's data, such as reindexing search or exporting a large search to a spreadsheet. Those tools do not keep the call open: they start a durable operation and return at once with its identifier.
| Tool | What it does |
|---|---|
The operation's start tool, for example search_reindex | Checks the input and the permission, starts the operation, and returns operationId, status, and pollInterval. |
operation_get | Returns the status, the progress, and the result or error once it ends. |
operation_cancel | Asks the operation to stop at its next safe point. |
- An operation is
working, thencompleted,failed, orcancelled. - A bulk operation keeps going when one item fails, and its result lists the failed items.
- The caller is notified when the operation ends.
- Only the caller, or a user of the same tenant with
operations.manage, can read or cancel it; anyone else gets "not found". - An operation record is kept for 7 days after it ends, and a result URL expires 24 hours after it is issued.
The design names the first operations, ported from BPMS 3.x: search reindex, exports of filing, task tray, and report searches, bulk task reassignment and closing, user import, and bulk filing creation, transfer, and closing.
This model works with any MCP client. When the MCP Tasks extension is supported by the platform's MCP library, operations will also be offered as MCP tasks, with the same identifiers, statuses, and permissions.