MCP access tokens

An MCP access token lets an MCP client, such as an AI assistant, act on your behalf on the BPMS.ai MCP server at /mcp. You create it while signed in, and the client sends it as a bearer token. It acts as you: the same tenant and the same authorities, read from your roles on every check, so it can never do more than you can.

Each token works in one place only. An MCP access token authenticates only at /mcp, and the session token you get when signing in authenticates only under /api/: an MCP access token cannot call the API, nor create another token. The MCP server and its tools are described in the MCP tab, which is still being designed.

Each operation is called with the session token of your sign-in, described in Authentication, and works only on your own tokens.

Create an MCP access tokenCopy Anchor Link

curl -sS -X POST -H "Authorization: Bearer $TOKEN" "$BPMS_URL/api/v1/mcp/access-tokens"

The request has no body. It answers 201 with the token's id and value:

{"id": 42, "token": "bpms_<token>"}

The value is shown only this once, and the answer carries Cache-Control: no-store. Keep it in the MCP client's configuration and never commit it to version control. A session that may only change its password cannot create one.

List your MCP access tokensCopy Anchor Link

curl -sS -H "Authorization: Bearer $TOKEN" "$BPMS_URL/api/v1/mcp/access-tokens"

It answers 200 with your open MCP access tokens, newest first, without their values:

[{"id": 42, "openedAt": "2026-11-10T09:00:00Z", "lastUsedAt": "2026-11-10T10:15:00Z"}]

lastUsedAt is when the token last authenticated at /mcp, recorded to the minute, and null before its first use.

Revoke an MCP access tokenCopy Anchor Link

curl -sS -X DELETE -H "Authorization: Bearer $TOKEN" "$BPMS_URL/api/v1/mcp/access-tokens/42"

It answers 204. From the next request, /mcp refuses that token with 401; your other tokens and your sign-in sessions keep working. Every attempt, successful or not, is recorded in the audit log.

RulesCopy Anchor Link

• MCP access tokens do not expire, and opening one closes none of your other sessions.
• A user keeps at most 10 open MCP access tokens. At that limit, creating another is refused with 409 and opens nothing: revoke one first. The operator changes the limit with the configuration property bpms.auth.session.max-access-tokens-per-user, at least 1.
• A token stops working when it is revoked, and when its user or tenant is no longer active. Disabling or deleting the user, resetting the user's password, and the lockout after too many failed sign-ins close all of the user's tokens; see Users. Signing out closes only the session that signs out.
• The app agent uses an internal token of its own, which is never listed, cannot be revoked here, and does not count against the limit.
• The same 404 answers a token that does not exist, is already revoked, or belongs to another user, so nobody can probe the tokens of others.

ErrorsCopy Anchor Link

At /mcp, a missing, unknown, revoked, or foreign token gets the same 401 core.authentication-required with WWW-Authenticate: Bearer.

In the OpenAPI document, the operations are createMcpAccessToken, listMcpAccessTokens, and revokeMcpAccessToken, under the mcp tag.