Formwork MCP tools and resource types reference

This is the complete reference for what an AI assistant or a script can do through Formwork's MCP server. You don't need it to use Claude or ChatGPT with Formwork; they discover all of this on their own. It is here for people writing scripts or pipelines, and for anyone who wants to know exactly what the AI can and cannot touch.

For connecting an assistant, see Connect Your Own AI via MCP. For scripts and CI, see Accessing MCP with a machine token.

How calls work

Endpoint: POST https://app.openregulatory.com/mcp, JSON-RPC 2.0 over HTTP. Send Content-Type: application/json and Accept: application/json, text/event-stream. Authenticate with a bearer token: either the one your AI tool obtained by signing in, or an API token (fw_...).
Stateless: no initialize handshake or session is required; every request stands alone. The initialize response does tell the client which company and access level the connection has.
Company scope: every call runs against the single company the connection is bound to. There is no way to reach another company through the same connection.
As you: the connection acts as your user. It sees what you can see and changes only what you could change. Read-only connections get the five read tools; read-and-write connections get all nine.
Results: tools/call answers carry the tool's JSON result under result.structuredContent (and as text under result.content).

Concepts that apply everywhere

Resource types. Everything in Formwork is addressed by a resource_type string (document, hazard, capa, ...) and a UUID id. The full list is below; describe_formwork_schema returns it at runtime.

Items. Every item returned by a query or read has id, human_display_text (the title with its identifier where one exists, e.g. HAZ-7 Electrical shock, cut at 80 characters) and link (the full URL of the item in Formwork), plus the type's own fields.

Pagination. Queries return { success, total, offset, limit, items }. limit defaults to 50 and is capped at 200. When there is more, a note says which offset to pass next.

Rich text. Fields typed markdown (document and record content, most descriptions, test steps and expected) accept Markdown on write and return Markdown on read; Formwork renders them as rich text.

Drafts for reviewable content. Creating a document, record, design or risk item, CAPA or change request produces a draft. Updating only works on items that are drafts and that you may edit. Items that are approved, released, under review, or deleted from their release refuse with a forbidden answer. For a released document or record, use dispatch_formwork_agent with new_document_or_record_draft to get a new editable draft first. Items without a review lifecycle - tasks, task groups and projects, folders, roles, trainings, comments - are created and updated directly and take effect immediately; creating an assigned task, for example, notifies its assignees.

Never through MCP: approving, releasing, rejecting, archiving, restoring, deleting or moving anything. Those stay in the Formwork UI.

Filters shared by many types.

archived (false by default, true, any): applies to everything that can be archived. Archived items are excluded unless asked for.
for_future (true, false; omitted lists both): for product-release items, whether the item is marked for a future release.
deleted (false by default, true, any): for product-release items, whether the item was deleted from its release.
query: text search on the title (typo-tolerant for documents and records, exact substring elsewhere).
product_release_id, product_id, folder_id, status: where the type has them.

Product-release items (the design and risk sections below) can also return change_history (added, modified, unchanged, deleted compared to the previous release) and for_future, and accept for_future: true|false as an update relation to move the item between the current and a future release. Not every type supports all of these: test runs, run sets, design-input systems and the probability and severity categories carry only a subset, so check describe_formwork_schema for the type before relying on one.

Relations. Fields ending in _ids (e.g. user_need_ids) take an array of UUIDs and replace the full set, with one exception: attachment_signed_ids adds the listed uploads and keeps the existing attachments, and remove_attachment_ids removes only the attachments listed. A pipeline that replaces evidence must remove the old file explicitly. Ids must belong to the same company, and for release items to the same release.

Errors. Most failures answer { success: false, error: "...", code: "..." }. Validation failures are the exception: they answer { success: false, status: "validation_error", ... } with no error or code, and name the fields that were wrong in operation-specific keys, for example missing and invalid on create and update, or kind and invalid on dispatch_formwork_agent. Check success rather than code alone. Common codes:

code	meaning
`unknown_resource_type`	no such type; the message lists the known ones
`not_found`	no item with that id in this company
`forbidden`	the item is not editable by you: released, under review, deleted, or you lack access
`validation_error` (returned as `status`, see above)	fields missing or invalid; `missing` lists required fields you left out, `invalid` maps fields to reasons (`unknown field`, `field not editable`, `must be a UUID`, `is not a valid date, use YYYY-MM-DD`, model messages with `(allowed: ...)` for enums)
`not_creatable`, `not_updatable`, `not_traceable`	the type does not support that operation
`invalid_arguments`, `upload_rejected`, `invalid_upload_url`, `missing_file`	file uploads, see below

Unknown filters answer unknown filter(s): x (allowed: ...); a bad enum value answers invalid value "x" for filter y (allowed: ...).

The tools

Read tools

describe_formwork_schema — resource_type (optional). Without an argument, lists every resource type with its queryable, creatable, updatable and traceable flags. With one, returns that type's description, query filters, required and optional create fields, editable update fields and relations, read fields and traceability fields. Call it whenever you are unsure about a contract.

query_formwork_resources — resource_type (required), filters (object), limit, offset. Lists items matching the filters, paginated as described above. Order is only defined where a type documents it, for example activity newest first and tasks and task groups by position. For other types do not rely on the order: page through all results rather than treating the first page as the most recent.

read_formwork_resource — resource_type, id (both required). Returns the item with all its read fields and traceability links. Reading an unreleased version of a document or record adds a warning naming the latest released version; reading an item deleted from a release says so.

search_formwork — query (required, up to 200 characters; body-content matching inside documents and records needs at least 3 characters, titles match from 2), scope (qms by default, manual, templates, all), limit.

qms searches every queryable type by title, and documents and records also by body content (including uploaded PDFs, Word and Excel files, and synced Google Docs). Content matching is a literal substring, so short distinctive stems (evaluat, nonconform) beat long phrases. Document and record hits carry content_snippet, matched_field (title or content) and, when the match is in an older version, matched_version_id. Title matches come first; the rest is ordered by recency, not relevance.
manual searches this manual and returns the best two articles with the relevant passage.
templates searches OpenRegulatory's public document templates.

trace_formwork_resource — resource_type, id. Returns the ids of everything linked to the item across the design and risk graph (for a hazard: its hazardous situations, harms, risk table entries, user needs, failure modes, ...), plus its review where the type is reviewable. Only for types marked traceable.

Write tools

create_formwork_resource — resource_type, attributes (object). Creates the item: a draft for reviewable content, a live item for types without a review lifecycle (tasks, folders, roles, trainings, comments). Missing required fields come back in missing; unknown ones in invalid.

update_formwork_resource — resource_type, id, attributes. Changes editable fields and relations on an item you may edit: a draft for reviewable content, any editable item otherwise. Anything not listed as editable for the type is rejected as field not editable.

upload_formwork_file — filename (required), then exactly one of data (base64, at most 1 MB decoded) or byte_size (to get a one-time upload URL), optional content_type. Answers with handles:

attachment_signed_id: pass it in attachment_signed_ids of a document, record, system test run or user test run to attach the file, or as file_signed_id when creating a custom_file_document or custom_file_record to make the file the document itself.
blob_url (PNG, JPEG, GIF, BMP only): embed as ![alt](blob_url) in Markdown content to place the image inline.

With byte_size, the answer instead holds upload_url, http_method (POST), multipart_field (file) and expires_at. POST the file there as a multipart form part named file within 10 minutes; the URL works once and needs no token, and its answer carries the same handles. Handles are valid for 24 hours; files that are never attached are removed after that. The per-file limit is 15 MB on free plans and 150 MB on paid plans. Viewers cannot upload.

dispatch_formwork_agent — kind (required), args (object). Runs a compound operation:

release_readiness with { product_release_id } (or { product_id } for the latest release): the same read-only sanity check as the release page, across records, change requests, risk items, design items, tests and test runs. Changes nothing.
send_for_review with { resource_type, id, reviewer_role_ids: [...], comment?, criteria? } for a document, record, CAPA or change request that is a draft you may edit; or with { resource_type, product_release_id, reviewer_role_ids: [...], comment?, criteria? } for a product-release type (hazards, design inputs, user needs, ...), which sends the whole list of that type in the release as one batch review. Creates the review and its requests; it never approves or rejects.
new_document_or_record_draft with { resource_type: "document"|"record", id }: creates a new editable draft version of an approved document, or of a record carried over unchanged from an earlier release, and returns the new draft's id.

Resource types

For each type: what it is, its query filters, what create needs (required, then optional), what update allows (fields, then relations). Filters and fields shared by many types (archived, for_future, deleted, query, change_history) are described above and not repeated. Read-only types say so.

Documents and records

document — a QMS document written in Formwork (SOP, plan, procedure, work instruction). Draft → under review → approved. Filters: status (draft, under_review, approved, review_rejected), query, folder_id. Create: none required; optional title, content, template_id, folder_id, attachment_signed_ids. Update: title, content; relations attachment_signed_ids, remove_attachment_ids. Reads return version, content and attachments.

custom_file_document — a QMS document uploaded as a file. Its file content is not readable through MCP (search still matches it). Filters as document. Create: required file_signed_id; optional title, folder_id, convert_to_markdown (when true, an AI job turns the file into a native document shortly after and removes the uploaded one). Update: title.

google_doc_document — read-only. A QMS document backed by a Google Doc or Sheet; google_doc_url links to it. Filters as document.

record — evidence written in Formwork (meeting minutes, checklists, audit logs), QMS-wide or scoped to a product release. Draft → under review → released. Filters: status (draft, under_review, released, review_rejected), product_release_id, product_id, qms (true for QMS-wide only, false for product records only), folder_id, query. Create and update as document. Reads add product_name, version_title, product_release_id.

custom_file_record — evidence uploaded as a file. Filters as record; create and update as custom_file_document.

google_doc_record — read-only. Evidence backed by a Google Doc or Sheet. Filters as record.

folder — container for documents or records. Filters: query, parent_folder_id, product_release_id, product_id, content_type (documents, records). Create: required title, parent_folder_id. Update: title. Reads return full_path.

comment_thread — a comment thread on a document or record (threadable_type is one of the six document and record types). Filters: resolved, threadable_type, threadable_id. Create: required threadable_type, threadable_id, content (starts a thread with a first comment). Not updatable; reading returns the thread's comments and, for anchored threads, the quote it discusses. Resolving is in-app only.

comment — one comment in a thread. Filter: comment_thread_id. Create: required comment_thread_id, content. Not updatable; resolved threads are read-only.

review — read-only. A review on a document, record, CAPA, change request or batch review. Filters: status (waiting, approved, rejected), reviewable_type, reviewable_id. Reads return comment and criteria.

activity — read-only. The event timeline of an item (created, edited, archived, released, review requested, review approved, ...), newest first. Filters: trackable_type, trackable_id.

Quality processes

capa — corrective and preventive action. Filters: query, status (open, closed). Create: required title, description; optional detected_at. Update: title, description, detected_at, root_cause_analysis, potentially_adverse_implications, verification, validation, incident_id, root_cause_analysis_completed_at, actions_defined_at, verified_at, validated_at.

capa_action — one action inside a CAPA; the CAPA must be a draft. Filter: capa_id. Create: required capa_id, description; optional deadline_kind (date, description), deadline_at (YYYY-MM-DD), deadline_description. Without a deadline, deadline_at defaults to one year from today. Update: the same fields except capa_id.

non_conformity — a process or product not meeting a requirement, optionally linked to a CAPA and an incident. Filters: query, status (open, closed), severity (minor, major), capa_id. Create: required title, description, detected_at; optional capa_id, incident_id, severity. Update: title, description, severity, detected_at, notified_body_validation, audit_evidence, correction, capa_id, incident_id.

incident — a post-market event on a product. Filters: query, product_id, serious, status (draft, released). Create: required title, description, product_id, incident_category_id; optional happened_at, serious. Update: title, description, serious, happened_at, incident_category_id.

incident_category — a product's own incident taxonomy; resolve one before creating an incident. Filters: query, product_id. Create: required product_id, title; optional description. Update: title, description.

change_request — a proposed change to a product; significant_change follows MDCG 2020-03. Filters: query, product_id, product_release_id. Create: required title, significant_change, significant_change_rationale, product_id; optional description, product_release_id (omit to scope to a future release). Update: title, description, significant_change, significant_change_rationale, product_release_id.

supplier — an entry in the list of qualified suppliers. criticality_or_custom is a criticality (A = yearly, B = every 2 years, C = every 3 years) or a custom cycle such as 18 months; last_evaluated_on and next_evaluation_before are derived from released evaluation records and not writable. Filters: query, category, status (draft, approved, blocked). Create: required title; optional description, category, criticality_or_custom, status. Update: those fields; relation record_ids (the evaluation records).

People, roles and training

company — read-only. The one company this connection belongs to; returns name.

user — read-only. A member of the company: name, email. Filters: query, role_id.

role — a company role; users belong to roles, trainings are assigned to roles. Creating or updating requires admin access. Filters: query. Create: required title; optional description, user_ids, training_ids. Update: title, description; relations user_ids, training_ids, owned_document_recording_ids.

training — a training assignable to roles; validation_kind is simple (a checker confirms) or quiz (auto-graded questions). Filters: query, validation_kind. Create: required title; optional description, validation_kind, due_within (no_due_date, one_week, one_month), minimum_required_quiz_score, in_person, checker_role_id, document_ids (approved documents as material), role_ids. Update: the same fields; relations document_ids, role_ids. Reads add per-status user counts.

training_question — a multiple-choice question on a quiz training. Filter: training_id. Create: required training_id, content, options (an array of { content, correct }, at least two, exactly one correct). Update: content only; recreate the question to change options.

training_request — read-only. One user's assignment of a training. Filters: training_id, user_id, status (pending, overdue, completed, checked). Reads return due, completed and checked dates plus user_name and training_title.

Tasks

task_project — a project of to-do tasks; kind is regular, template, onboarding (read-only) or roadmap. Filters: query, kind. Create: required title. Update: title. Reads return tasks_done and tasks_total.

task_group — a group of tasks in a project. Filters: query, task_project_id. Create: required title, task_project_id. Update: title.

task — a to-do item, optionally linked to the item it is about (taskable_type + taskable_id: documents, records, CAPAs, incidents, non-conformities, change requests, suppliers, risk and design items). Filters: query, done, task_project_id, task_group_id, assigned_user_id, taskable_type, taskable_id. Create: required title; optional description, task_group_id, task_project_id (omit both to use the company's default project), taskable_type, taskable_id, assigned_user_ids, remind_at. Update: title, description, done, remind_at, task_group_id; relation assigned_user_ids.

Products and releases

product — a medical device; creating one also creates a draft v0.1.0 release. Filters: query. Create: required name, kind (software, hardware, software_and_hardware), description; optional safety_classification (A, B, C). Update: those plus setting_design_outputs, setting_detailed_designs, setting_p0.

product_release — a release of a product; most technical documentation lives on a release, and it is editable only while in draft. Not creatable through MCP. Filters: product_id, product_name, status (draft, released), query. Update: title, description. Reads return title_with_product.

Design controls

All types here belong to a product release (product_release_id is required on create) and carry status (draft, under_review, approved, rejected) as a filter and read field. Most also carry for_future, deleted and change_history; see the note on product-release items above for the exceptions.

stakeholder — a person or group affected by the device. Create: required title, description; optional user_need_ids. Update: title, description; relation user_need_ids.

user_need — what a stakeholder needs the device to do. Create: required title, description; optional stakeholder_ids, design_input_ids, user_test_ids, hazard_ids. Update: title, description; relations stakeholder_ids, design_input_ids, hazard_ids, user_test_ids.

user_test — verifies user needs, with structured steps and expected results. Create: required title, description, steps, expected; optional user_need_ids, risk_control_ids. Update: title, description, steps, expected; relations user_need_ids, risk_control_ids.

user_test_run_set — a user test session (UTR); each included test becomes a user_test_run. Filters: query. Create: required title; optional description, user_test_ids. Update: title, description; relation user_test_ids. Reads return status_counts.

user_test_run — one test's execution in a run set; created by including the test in the set, never directly. Filters: user_test_run_set_id, status (planned, success, partial_success, failure, skipped). Update: status, results; relations attachment_signed_ids, remove_attachment_ids (evidence files). instructions, steps and expected are copied from the test and read-only.

design_input — an engineering requirement derived from user needs (shown as "Software Requirement" for software-only products). Filters add design_input_system_id and kind (software, hardware, system). Create: required title, description, kind (auto-set for single-kind products), category_or_custom; optional design_input_system_id, user_need_ids, detailed_design_ids, system_test_ids, design_output_ids, failure_mode_ids, risk_control_ids. Update: title, description, kind, category_or_custom; relations as the optional create fields.

design_input_system — a subsystem grouping design inputs; systems can nest. Filters: parent_id, query. Create: required title, prefix; optional description, parent_id. Update: title, prefix, description; relation parent_id. Only while the design inputs list is not under review.

design_output — a verifiable artifact satisfying design inputs; only when the product has design outputs enabled. Create: required title, description; optional design_input_ids, system_test_ids, record_ids. Update: title, description; the same relations.

detailed_design — an implementation spec refining a design input; only when the product supports detailed designs. Create: required title, description; optional design_input_ids. Update: title, description; relation design_input_ids.

system_test — verifies design inputs (shown as "Software Test" for software-only products). Create: required title, description, steps, expected; optional design_input_ids, design_output_ids, risk_control_ids. Update: title, description, steps, expected; the same relations.

system_test_run_set — a system test session (STX). As user_test_run_set, with system_test_ids.

system_test_run — as user_test_run, with system_test_run_set_id.

Risk management

Same conventions as design controls: each belongs to a product release and carries status, and most carry for_future, deleted and change_history.

preliminary_hazard — an early hazard-analysis entry. Create: required title, description; optional hazard_ids. Update: title, description; relation hazard_ids.

hazard — a source of potential harm. Create: required title, description; optional user_need_ids, preliminary_hazard_ids, failure_mode_ids. Update: title, description; the same relations.

hazardous_situation — circumstances under which a hazard can cause harm. Create: required title, description. Update: title, description.

harm — an injury or damage, rated with a severity category. Create: required title, description, severity_category_id. Update: title, description, severity_category_id.

severity_category — a severity tier of the release's risk matrix. Not creatable. Filters: query. Update: title, description.

probability_category — a probability tier of the risk matrix. Not creatable. Filters: query. Update: title, description, lower_limit, upper_limit.

risk_table_entry — one row of the risk table: one hazard, one hazardous situation, one harm, with probabilities. Filters add hazard_id, harm_id. Create: required hazard_id, hazardous_situation_id, harm_id, p1, p2, description; optional p_reduction, risk_control_ids. Update: description, p0, p1, p2, p_reduction, hazard_id, hazardous_situation_id, harm_id, severity_category_post_id; relation risk_control_ids.

risk_control — a mitigation; kind follows the ISO 14971 hierarchy: inherently_safe_design, protective_measure, information_for_safety, training. Filters add kind. Create: required title, description, kind; optional design_input_ids, system_test_ids, user_test_ids. Update: title, description, kind; the same relations.

failure_mode — a way the device can fail, traced to hazards and design inputs. Create: required title, description; optional hazard_ids, design_input_ids. Update: title, description; the same relations.

Worked example: filing test evidence from a pipeline

query_formwork_resources with resource_type: "product_release", filters: { product_name: "MyDevice", status: "draft" } to find the release.
create_formwork_resource with resource_type: "system_test_run_set", attributes: { title: "CI run 2026-09-06", product_release_id: ..., system_test_ids: [...] }.
query_formwork_resources with resource_type: "system_test_run", filters: { system_test_run_set_id: ... } to get the run ids.
upload_formwork_file with filename and byte_size, then POST the report to the upload_url.
update_formwork_resource on each system_test_run with attributes: { status: "success", results: "...", attachment_signed_ids: [...] }.

The run set records no author; each run's update records the token's owner as the person who assessed it. Test run sets have no review of their own; they become part of the release when a person releases it in Formwork.