MCP server (AI assistants)

TeamCraft has a built-in Model Context Protocol server, so an AI assistant such as Claude Code, Claude Desktop or any other MCP client can work with your PDM data: find items, explain structures and where-used, summarise what changed between revisions, check a BOM before a release, prepare change orders, summarise and raise change requests, and check simulations and their results.

The assistant works with your rights: it signs in with one of your personal access tokens and every tool calls the same business logic as the REST API and the web interface. It can read what you can read, it can draft change orders if you are a CAD editor, and – like everyone signed in – raise change requests and comment on them. It cannot submit, approve, release or make anything obsolete, and it cannot triage, accept, defer or reject change requests. Those decisions stay with people.

The same tools also power the optional server-side assistant, Ask TeamCraft. It needs no client, only an AI provider (Anthropic, OpenAI-compatible or a local model) configured on the server.

Endpoint

The HTTP endpoint is stateless. Each POST carries one JSON-RPC 2.0 message (or a batch), and the answer is application/json. Notifications get 202 Accepted. There is no event stream (GET returns 405) and no session id. Protocol revisions 2025-06-18, 2025-03-26 and 2024-11-05 are accepted. Without a valid token the endpoint answers like the rest of the API, with 401 and a JSON error.

With TEAMCRAFT_LOCAL_AGENTS=off the endpoint refuses every call with 403 and a JSON-RPC error naming the setting, for every token: the desktop app’s agent, the teamcraft mcp bridge and any other client (GET /api/v1/me then reports capabilities.mcp: false). The built-in assistant is not affected. See Local agents for what this setting can and cannot enforce.

Setup

Create a personal access token under Account → API tokens. Give it an expiry, and give each assistant or machine its own token so you can revoke it on its own. Prefer a scoped token: read_only (only the read-only tools), write (all tools, but no approving on the REST API) or mcp_only (see Token scopes).

Claude Code

claude mcp add --transport http teamcraft http://localhost:8080/api/v1/mcp \
  --header "Authorization: Bearer <token>"

Use the server’s public https:// URL for a shared installation. Then ask, for example: “What changed in ASM-000003 between B and C?”, “Is ASM-000003 ready to be released?”, “What problems were reported on PRT-000012?”, “Which simulations are out of date after yesterday’s release?”, “Summarise the results of SIM-000003 rev B vs A”, or use one of the prompts below (/mcp__teamcraft__release_check).

Clients that only speak stdio

Some clients, such as Claude Desktop, start MCP servers as local processes. The teamcraft binary bridges them to the HTTP endpoint:

{
  "mcpServers": {
    "teamcraft": {
      "command": "teamcraft",
      "args": ["mcp", "--server", "https://pdm.example.org"],
      "env": { "TEAMCRAFT_TOKEN": "<token>" }
    }
  }
}

The bridge reads newline-delimited JSON-RPC from stdin, forwards each message to POST /api/v1/mcp and writes the answers to stdout. It writes nothing for notifications, and diagnostics go to stderr. The token comes from TEAMCRAFT_TOKEN or --token-file <path> and is never printed. --server defaults to TEAMCRAFT_SERVER, or else http://localhost:8080. Messages longer than 4 MiB are rejected.

Tools

All tools return compact JSON that uses item numbers and revision codes instead of internal ids. It is sent both as text and as structuredContent. Long lists are capped and marked with truncated: true: expanded BOMs stop at 2000 rows, other lists at 500 entries, and the whole result at 1 MiB.

Revisions are given as item plus revision (latest by default). In the change order tools, items are given as PRT-000012 (meaning its in-work revision) or PRT-000012/B. If create_change_draft cannot add one of the revisions, it cancels the new draft again, so nothing half-finished is left behind. In create_change_request, PRT-000012 names the item and PRT-000012/B the revision the problem was found in (at most 100 items); every item is resolved before the request is created, so a typo creates nothing. compare_simulation_results defaults like compare_revisions: to = latest, from = the revision before it.

Each tool declares MCP annotations. The read tools are readOnlyHint, and no tool is destructiveHint. Clients that ask before running write tools will ask before create_change_draft, add_to_change, create_change_request, propose_result_values and comment_change_request.

Prompts

Safety model

• Same rights as the user. The token identifies a user, and every tool checks that user’s role and project groups, exactly like the REST API. A viewer’s assistant can only read, raise change requests and comment on them – the same as a viewer in the web interface.
• Restricted groups. Every tool result is filtered by the user’s read permissions (restricted project groups): an item, change or request of a restricted group the user is not a member of is reported as not found, with the same message as an unknown number; BOM lines and other links to such items come back as placeholders with "restricted": true and no number or name, and lists report how many entries they left out (hidden_parents, hidden_dependents, hidden_changes). The server instructions tell the model not to guess or retry. Rights are read on every HTTP request; the messages of one JSON-RPC batch share that snapshot.
• Copying out of restricted groups. Text other users typed can try to make a model copy restricted content into a comment or draft that those users can read. The built-in assistant refuses its text-writing tools for the rest of a run once it has read such content; an external MCP client gets no such check and acts with the full rights of the token’s user (see Notifications, e-mail, chat, webhooks, assistant).
• No decisions. There are no tools to check out, upload, edit BOMs, submit, review, release or make anything obsolete, and none to triage, assign, accept, defer, reject or withdraw a change request. The assistant can only prepare a draft change order, which the user then opens, completes (reviewers) and submits in TeamCraft, raise a change request that CAD editors then triage, and post a comment.
• Audit. Drafts, added revisions, change requests and comments show up in the audit log under the user’s name, like any other action; a new request and a comment notify the same people as in the web interface.
• Errors. User errors, such as an unknown item or missing rights, come back as tool errors with the same message the web interface shows. Internal errors are logged on the server, and the assistant only gets a generic message.
• Tokens. Treat the token like a password. It is stored hashed on the server, can expire, and can be revoked on the account page. The bridge never prints it.