Skip to main content
PlanRelevé Wiki

API and MCP integrations

PlanRelevé exposes organization integrations through a stateless Model Context Protocol (MCP) endpoint. It lets a compatible client query PlanRelevé projects and, only when you explicitly authorize it, change them. It uses a bearer token: anyone holding the secret can act within its scope. The administration page does not issue a separate general-purpose REST API key.

PlanRelevé MCP server administration page showing the organization enable switch, endpoint, setup command without a real token, read-only token creation controls and the token inventory, still empty.
PlanRelevé MCP server administration page showing the organization enable switch, endpoint, setup command without a real token, read-only token creation controls and the token inventory, still empty.

Prerequisites and permissions

UI path: account menu (your initial, top right) → Administration → MCP server.

Only an organization Owner or Admin can open this page, enable MCP, create tokens or revoke them. The client must support MCP over HTTP (Streamable HTTP) with an Authorization: Bearer header. A token:

  • is limited to the creator's organization;
  • acts as its creator, not as a new service account;
  • has project permissions rechecked on every call;
  • is Read-only unless Allow write tools (read-write token) was selected;
  • stops working if revoked, if its creator is deactivated, deleted or no longer belongs to the organization, or while MCP is disabled organization-wide.

MCP is disabled at the organization level by default. The token is accepted only on /mcp and /mcp/files; it is not a general key for the web routes or the application's internal API.

Enable the MCP endpoint

  1. Open Administration → MCP server.
  2. Select Enable the MCP server for this organization.
  3. Wait for Saved. If the save fails, the checkbox returns to its prior state.
  4. Under Endpoint, copy the URL shown; it ends in /mcp for the current PlanRelevé host.

The page shows the Claude Code setup command; for another compatible client, carry over the same endpoint and header. Example, with a fake token:

claude mcp add --transport http planreleve https://your-instance.example/mcp --header "Authorization: Bearer <TOKEN>"

Never put a real token into a repository, plan, screenshot, support ticket, browser-side code or shared command history.

While the checkbox is clear, the endpoint refuses every connection, even one presenting a valid active token. This is an organization-wide pause; it does not convert or delete tokens.

Create a read-only token

Read-only is the safe default for reporting, search and integration testing.

  1. Under Access tokens, enter a specific Token name, such as Claude Code — review laptop.
  2. Leave Allow write tools (read-write token) clear.
  3. Select Create token.
  4. Immediately copy the value that starts with ptk_ into the client's secret store. The message Copy this token now — it will never be shown again. is literal.
  5. Reload the page: the value disappears and the inventory shows the name, prefix, Read-only, creator, creation date, Never under Last used and Active.
  6. Configure the client and make a simple ping or list_projects call. Then reload the page and verify Last used is populated.

PlanRelevé retains only a hash of the secret and a short prefix to identify it; it cannot show the raw value again. If you lose it, revoke the token and create another.

Creator scope and reads

A token acts as the person who created it. On every call, PlanRelevé checks again:

  1. that the token is active;
  2. that its creator is still active and still belongs to the organization;
  3. that the organization has MCP enabled;
  4. that the project belongs to the same organization;
  5. that the creator still holds the required permission on that project.

Because token creators are owners or administrators, they have access to every organization project; if their role changes, the token's future scope follows. A resource from another organization and a nonexistent project identifier intentionally produce the same project not found result, while forbidden means the creator lacks the required permission on that project.

Start with the list_projects tool; it returns the active projects the creator can view, with the UUIDs every other tool needs. A read-only token can read, among other things, confirmed counts (get_counts), the legend, the bill of materials, the estimate, parts, detections, suggestions, detection quality, detection job status and confirmed attribute values per class (get_attributes). Counts come from reviewed data: candidates are not silently promoted, and amounts are CAD. Validate quantities against the current project state in PlanRelevé.

get_export_links requires the creator's export permission and covers every download the project has — the estimate PDF, the takeoff workbook, the annotated plan, the cabling and piping PDF, and the grouped, instances and cabling CSVs. These links point back to the web application and require a logged-in browser session: the token does not download those files. Only the durable artifacts of an approved revision additionally offer a /mcp/files/<id> path downloadable with the token; they are unavailable while Revisions are parked.

What the server does not expose

The list returned by tools/list is deliberately narrower than the assistant's:

  • Supplier-quote tools — list requests, read a received file, import prices, void a price — stay with the assistant. They are organization-level operations, and the import runs through an approved action plan that MCP's immediate-execution model has no equivalent of.
  • Web search and page fetching are not project tools and are not exposed either.
  • Tools for a feature turned off for your organization, or for a parked surface, are hidden rather than deleted: while Revisions are parked their tools do not appear in the listing, instead of being advertised and then answering "not enabled". They return the moment the flag flips.
  • An archived project can be read and exported, but no write reaches it — through the application, the assistant or MCP alike.

Opt in to write access only when required

For a read-write token, repeat the creation flow and select Allow write tools (read-write token) before Create token, only when the client must change data. Write tools can change estimate settings, free lines, run pricing and labour, spare, the tax group, parts, assemblies, detection attributes, the legend, classes, detection statuses and the project name, and can also start a detection or a find-similar search, add an example or cancel a job; the exact tool list is advertised by the server. A detection started this way (run_detection, find_similar) is only queued: the computation runs in the browser. Open the project in a PlanRelevé tab first and keep it open; a job that no tab picks up within the minute fails.

MCP writes apply immediately. They do not use the action plan and creator approval of the AI assistant. Two gates still apply: the token must be read-write, and the creator must hold the required project review or edit permission. A read-only token neither advertises write tools nor accepts a write call.

Recommended measures:

  • a separate token per device or automation;
  • read-only whenever a report or export link is sufficient;
  • a fresh read immediately before a write, with the project UUID confirmed;
  • human confirmation in the client before every write tool, with no unattended destructive calls;
  • revocation as soon as the integration is no longer used.

There is no button to convert an existing read-only token to read-write. Revoke it and create a new secret with the required scope. Compare this boundary with AI assistant and approved actions and Members, roles and invitations.

Revoke, rotate and audit

UI path: Administration → MCP server → Access tokens. The inventory shows the name and prefix, Read-only or Read-write access, Created by, creation date, Last used and the Active or Revoked state.

  1. Identify the token by its name, creator and prefix.
  2. Select Revoke, then confirm.
  3. Verify the row changes to Revoked; clients using it lose access immediately.
  4. If every integration must stop, also clear the organization's MCP switch.

Also revoke a token when a device is lost, a workflow is retired, the token may have entered logs, or its creator leaves the organization. Recreate a token rather than trying to reuse a revoked or lost one.

The organization Audit log records MCP enable and disable, token creation and revocation, every write-tool call (successful or not), every failed call and every /mcp/files download; successful reads are not recorded. Last used is a coarse signal updated periodically, not a request-by-request log or a client transcript. For an investigation, review Audit & data → Audit log together with the client's authorized logs, without recording the token in them.

Connection recovery

  • 401: token missing, mis-copied or revoked, or creator deactivated. Replace a lost token; do not guess it from the displayed prefix.
  • 403 at the endpoint: MCP is disabled for the organization. Confirm the dashboard shows Enabled.
  • forbidden on a tool: the token authenticated, but its creator lacks that permission on the project; correct project access instead of issuing a broader shared token.
  • project not found: call list_projects again and use the returned UUID; do not reuse another organization's identifier.
  • Write tool missing or read-only error: a read-only token does not see write tools; create a purpose-specific read-write token only after weighing the immediate-write risk. Also check that the client uses tools/list.
  • No projects: confirm the creator can open the expected active project in the web application and that the client targets the correct PlanRelevé host.
  • Detection failed or empty: open the project in a PlanRelevé tab, keep it open, then start again; the computation runs there.

The endpoint is a stateless HTTP MCP server: requests use POST; it offers no SSE stream over GET and no session to delete. For data and privacy boundaries, see Security, privacy and Law 25, Organization administration and Troubleshooting.

See also