MCP Access

MCP access lets an outside AI agent read boards, review insights, and draft intents through the same governed tools the portal uses. Generate a token, point a client at one endpoint, and the agent gets the access you granted.

What MCP access is

Note

This page is about agents reaching into your workspace. For the other direction, registering external servers whose tools chat can call, see MCP Servers.

The platform speaks MCP itself. A connected agent gets the same board tools chat uses, filtered by token scope.

Generating a token

Generate tokens from Architect access in a workspace command center. You need workspace admin. An app board hub's Agent access creates a different credential: a repo binding.

The sheet includes plugin installation, OAuth sign-in, Generate a key, and a list of tokens, including those created by /login. A Plugin connections section lists every repo-binding credential in the workspace and lets you revoke each one. Signing In & Credentials covers that credential type.

Generating asks four things:

The token value (ck_mcp_live_…) appears exactly once, with setup snippets. After that, the list shows only label, scope, and last-used time.

You cannot view it again because only a hash is stored. Lost a token? Revoke it and generate another. Revoke takes effect on the next call and requires a confirmation word.

Connecting a client

The endpoint is https://platform.provenmap.com/api/mcp, authenticated with a bearer header. Wiring up a generic MCP client with a token you already hold:

claude mcp add --scope user --transport http provenmap \
  https://platform.provenmap.com/api/mcp \
  --header "Authorization: Bearer ck_mcp_live_..."

For hosts that read environment variables, use PMAP_MCP_TOKEN; add PMAP_MCP_URL for self-hosted endpoints.

Running the architect plugin? Do not generate anything yet. Its /login signs you in through the browser and configures the token for you. See The Architect Workbench. Signing In & Credentials has the decision table for every environment, including the ones that need a manual step.

What a scope opens

There are two scopes.

A read token gets board structure, nodes, edges, layers, archetypes, aspects, insights, intents, and hub status. A read + write token adds governed write tools and session tools.

Both scopes are on every plan, Free included. What an agent writes counts against the same plan limits as work done in the browser.

The tool set comes from the same registry chat uses, filtered by policy. Tools that need a human in the conversation and greenfield provisioning tools are never exposed.

Check the exposed tools preview before generating. It shows what the agent will have for that scope.

Restricting a token to one board

A board restriction limits every call to that board and its layers. Reads and writes outside the restriction are refused clearly.

A board-restricted token cannot create a new app board because new boards attach to the root, outside the restriction. An unrestricted token can.

Tip

Start an integration with a read token restricted to one board. Widen it to read + write or the whole workspace after you have reviewed the agent's behavior.

Working copies

Every MCP write joins a working copy owned by the person who generated the token. A shared token means shared work in progress, so each architect should generate their own.

The portal shows the same working copy. A coding-session change and a canvas edit stage in the same place:

• Committing accepts everything in the working copy and clears the undo log. It generates one board_diff intent for each governed root the session touched.

  Committing is not approving. Each new intent is a draft, and handing it to developers remains a separate human decision. See Intents.

• Discarding reverts everything since the session opened and reports what happened row by row: reverted, conflicted (someone else changed that row while your session was open), or skipped.

That is the write model: the agent can make real changes, you can discard the working copy in one action, and review stays with your team.

The same session, in the browser

The browser shows the working copy in the Topbar as "{n} uncommitted changes" plus the board count.

The pill is workspace-scoped and follows you across boards. When there is nothing uncommitted, it renders nothing.

Click it to open Uncommitted changes. Commit your changes asks for a title and summary, which becomes the proposal description. Discard asks "Discard your working copy?" and reports any rows it cannot revert cleanly.

Session tools

A read + write token automatically gets four tools for the same session, no extra grant:

A read-scoped token never sees them. Because both surfaces use one session, an agent can give you a preview to review in the browser, or clean up a session you opened by hand.

What's next