ProcessCraft MCP server and API
The MCP server gives AI agents access to your organization's procedures. An agent acts on behalf of a person — only with the scopes that person approves on the consent screen.
Quickstart: connect an agent in 5 minutes
01Add the server to your MCP client
Server URL: https://mcp.processcraft.pl/v1 (Streamable HTTP). Choose the client you use:
{
"mcpServers": {
"processcraft": { "url": "https://mcp.processcraft.pl/v1" }
}
}02Grant OAuth consent
On the first call, the client opens the ProcessCraft consent screen. Sign in, then choose a space and scopes (e.g., processes:read, drafts:write). You can revoke access at any time in your profile settings.
03Make your first call
Search for a procedure and fetch its published version. Procedure content is returned as data, not as instructions for the agent.
// 1. search for a procedure
search_processes({ "query": "unit handover" })
// 2. fetch the published version
get_process({ "id": "INS-0042", "version": "published" }){ "id": "INS-0042", "version": "3.1", "status": "PUBLISHED",
"title": "Unit handover from the developer", "steps": 7,
"owner": "Anna Nowak", "consistency": "CONSISTENT" }MCP: tools
This list comes from the server description (mcpServer.getInfo) — the same one the client receives over the MCP protocol.
| Tool | Required scope | AI credits | Description |
|---|---|---|---|
| search_processes | processes:read | no | Searches published procedures in the person's spaces |
| get_process | processes:read | no | Procedure version: steps, positions, criteria |
| get_bpmn | processes:read | no | The version's diagram as BPMN 2.0 XML |
| get_my_position | processes:read | no | The person's position and assigned procedures |
| list_spaces | processes:read | no | Spaces available to the person |
| list_positions | processes:read | no | The organization's position directory |
| create_draft_from_text | drafts:write, ai:use | yes | Draft from a process description |
| import_document | drafts:write, ai:use | yes | Draft from a document (DOCX, PDF) |
| patch_draft_graph | drafts:write | no | Changes a draft's steps and transitions |
| validate_draft | drafts:write | no | Validation and BPMN consistency status |
| generate_bpmn | bpmn:generate | no | BPMN diagram from a list of steps |
| request_approval | drafts:write | no | Submits a version for approval — a human approves |
| add_comment | comments:write | no | Comment in a step's discussion thread |
| review_process | ai:use | yes | AI review: gaps and inconsistencies |
| ask_procedures | ai:use | yes | Assistant's answer to a question about procedures |
| report_issue | comments:write | no | Reports a problem with a procedure to its author |
What an agent won't do
OAuth scopes and consent
| Scope | Allows | Allowed roles | AI credits |
|---|---|---|---|
| processes:read | Reading published procedures and diagrams | all roles | no |
| drafts:write | Creating and editing drafts, submitting for approval | Author, Administrator, Owner | no |
| bpmn:generate | Generating a diagram from a list of steps | Author, Administrator, Owner | no |
| ai:use | AI features: import, review, questions to the Assistant | Author, Approver, Administrator, Owner | yes |
| comments:write | Comments and problem reports | all roles | no |
Authorization: OAuth 2.1 with PKCE. On the consent screen, the person chooses spaces and scopes; the agent never gets more than that person's role allows. You can revoke access in your profile, and an Administrator can revoke it in the organization's agent list.
A call without the required scope fails with a FORBIDDEN error that includes the details.required_scope field.
Skills and Process-as-Skill
The skills package teaches an assistant to work with ProcessCraft: modeling steps, importing documents, reviewing, and running procedures over MCP.
- processcraft-modelerModels steps, positions, and decision gateways, and creates a draft from them.processes:readdrafts:writebpmn:generate14 KB
- processcraft-importerTurns existing documents into structured draft steps.drafts:writeai:use11 KB
- processcraft-reviewerFinds gaps and inconsistencies and leaves comments in threads.processes:readcomments:writeai:use12 KB
- processcraft-runnerGuides you step by step through a position's published procedure.processes:read11 KB
unzip processcraft-skills-1.2.0.zip -d ./skills/
# in a web client (e.g., claude.ai), upload the ZIP in the skills settingsProcess-as-Skill
You can export a published procedure as a Skill (ZIP) with its version number and step completion criteria. A human performs the export in the app — an agent does not publish or export versions.
Errors, limits, idempotency
Every error uses the same format; in MCP, the result also includes isError: true. The message field is a short technical description in English — branch your logic on code and details, not on the message text. request_id is the trace_id from the W3C traceparent header — include it in support requests.
{ "code": "FORBIDDEN", "message": "Missing required scope: drafts:write.",
"request_id": "8f2c41b6e0d94a7f9c3e5a1d2b7f6c08", "retryable": false,
"docs_url": "https://processcraft.pl/docs/errors#FORBIDDEN",
"details": { "reason": "scope", "required_scope": "drafts:write" } }| Code | HTTP | Retry | Meaning |
|---|---|---|---|
| VALIDATION_FAILED | 400 | no | Fix the fields listed in details.fields[] |
| UNAUTHENTICATED | 401 | no | Token expired — reauthorize |
| FORBIDDEN | 403 | no | Missing role or scope (required_scope) |
| PLAN_LIMIT_REACHED | 403 | no | Organization's plan limit reached |
| PAYMENT_REQUIRED | 402 | no | Organization is in read-only mode |
| AI_CREDITS_EXHAUSTED | 402 | no | Not enough AI credits |
| NOT_FOUND | 404 | no | Item does not exist or you don't have access to it |
| IDEMPOTENCY_CONFLICT | 409 | depends | Same key with a different payload, or operation in progress |
| RATE_LIMITED | 429 | yes | Too many calls — wait retry_after s |
| INTERNAL_ERROR | 500 | no | Error on our side — report the request_id |
Limits, pagination, and idempotency
- RATE_LIMITED (429) returns a Retry-After header — retry after the indicated time.
- Lists use cursor-based pagination: get the next page with next_cursor.
- Write commands accept an Idempotency-Key; a retry with the same key returns the original result.
- Plan blocks: PAYMENT_REQUIRED, PLAN_LIMIT_REACHED, AI_CREDITS_EXHAUSTED — with a resolve_url for the person.
Changelog
- MCP server 1.4.0New tool report_issue; FORBIDDEN returns details.required_scope.
- skills 1.2.0New skill processcraft-runner.
- API v1Breaking changeCursor-based pagination (next_cursor) instead of page numbers.