Last updated October 24, 2026
On this page
MCP Access
MCP access is the token-based way an outside AI agent reaches your workspace's board tools. Use it to let Claude Code, Codex, claude.ai, Cursor, VS Code or any other MCP client read your boards, and to let the workspace plugin change them.
Choose how to connect
- To change your workspace, use the workspace plugin. It closely orchestrates the write tools, so we recommend a Read + write token only for the plugin.
- Anywhere else, use a Read token. An agent can then read your boards, insights and work items, and change nothing.
Set up
Owners and admins only.
Open Workspace agent access on the root hub. Under Connect a client:
- Sign in with the plugin: for Claude Code and Codex on your machine. Install the workspace plugin, run
/pmap-workspace:login(changed 12 October 2026) and approve in the browser. The plugin adds ProvenMap to your client's MCP config itself. - Use a key: for any other client, or a machine where you can't approve a sign-in. Generate a token and paste it into the client.
App agent access on an app board's hub is a different credential: a repo binding for a coding agent. Signing In & Credentials covers it.
Connect a client with a token
Generate the token
Open Use a key. Name the token in Label, pick a Scope, and set Expires (days):
Choose Generate token.
Copy it into your client
Agent key generated shows the token (pmap_mcp_live_…) once. Below it are the Server URL and a tab for each client with the exact command or fields to copy.
Keep the token safe
We store only a hash of the token. If you lose it, revoke it in the Tokens list and generate another. Revoking takes effect on the next call.
Each token in the list shows when it was last used and the client it last connected from, such as claude-code 2.1.0. The client names itself. If you don't recognise it, revoke the token.
A client sends the token in one of two ways:
- As a header, to
https://platform.provenmap.com/api/mcp:Authorization: Bearer pmap_mcp_live_… - Inside the URL, for clients with only a URL field, such as a claude.ai connector:
https://platform.provenmap.com/api/mcp/k/pmap_mcp_live_…. Anyone who has this URL has the token, so treat it the same way.
What a token can do
A Read token gets board structure, nodes, edges, layers, archetypes, aspects, insights, work items, playbooks, hub status, the change record and connected documents. It changes nothing.
A Read + write token adds every write tool, in two groups:
Changed 30 September 2026: no token can publish a board. Publish from Publish, where you see what goes.
A discard also undoes deleting a node, with two exceptions. Child nodes stay moved out of the deleted node, and a layer board it owned stays a standalone board.
MCP Tools lists every tool with its scope and whether a discard undoes it.
Reads of connected documents use the personal connections of the person who generated the token. The agent sees only what that person's accounts show. See Provider Sources.
Both scopes are on every plan, Free included. An agent's writes count against the same plan limits as your work in the browser.
Review what an agent changed
Every change an agent makes through a token lands in that token's own working copy, apart from your edits in the portal. The changes apply to the board at once, and the working copy keeps what it needs to undo the board edits.
While a token has changes waiting, the top bar shows a pill: a count such as 2 plugin pushes, or your own uncommitted changes count when you have some too. Click it and find Plugin pushes awaiting commit, with one row per token, named by the token's label:
- Accept keeps the changes. The elements become plain board content, and no work item is created.
- Discard asks Discard this push?, then undoes every board edit the token made since its last accept or discard. Rows someone else changed in the meantime are left alone and reported as conflicted.
To undo something in the permanent group, change or delete it in the portal.
Session tools
A Read + write token gets four tools for its own working copy. Read tokens get none.
A commit accepts the token's changes the way Accept does: it creates no work items, so the preview lists none. An agent that wants work handed to a developer creates the work item with create_work_item.
commit_write_session takes the reason for the change as title, one line of 2 to 100 characters, and the longer why as summary, up to 2,000 characters. Both are stored with the commit.