# Govform MCP capabilities Source: https://govform.com/resources/documentation/article/33-14-mcp-capabilities Topic: Govform API & MCP **MCP API units:** For Cloud accounts, each `tools/call` is charged once by the operation it runs. Government Cloud accounts and libraries without an assigned account are exempt from these quotas. Initialization, tool discovery, resources and prompts do not use monthly units. ## MCP API units | Tool operation | Units | | --- | --- | | Darcy calls; Actions Log search/detail; status, summary, permission and export polling | **1** | | Lists, searches, full service reads, Response Hub pages up to 100 records and ordinary changes | **5** | | Full-definition saves, pages over 100 records, export start/download and roster stage/apply | **25** | Send one JSON-RPC message per HTTP POST. JSON-RPC batches are rejected before tool execution. Successful metered results include `_meta.govformsApiUsage`. Quota admission failures return a tool result with `isError: true` and details in `structuredContent.error`, including the error code, retry time and, for exceeded limits, allowance details. OAuth export-part and submitted-file download links each have a separate 25-unit class for Cloud accounts. Operations affecting more than one account charge once per affected Cloud account and group authorised libraries that share each balance. Govform MCP lets an AI agent inspect and manage Govform through structured, permission-aware tools. It can work with form designs and with Response Hub data while keeping those areas separate. ## What an agent can do Depending on the access granted, an agent can: - find libraries, services and reusable patterns; - inspect form structure, settings, conditions, actions and deployment status; - create and update forms through structured Govform tools; - prepare deployments and undeployments; - list Response Hub data collection services and collections; - manage collection lifecycle, cohorts, respondent assignments and roster imports; - read immutable submitted response versions and review comments; - claim, return, accept, release, reassign or complete Response Hub reviews; - inspect respondent communications and the collection audit trail. Govform also exposes guidance resources that help an agent understand the platform model and choose a safe tool before making changes. ## You choose the access Interactive MCP uses your Govform sign-in. When connecting an MCP client, every library has three independent access choices: ### Form designs - **No access** — the agent cannot see forms in that library. - **Read-only** — the agent can inspect forms and deployment status. - **Changes require approval** — changes need your recorded approval in Builder. - **Changes allowed automatically** — changes may run within your current role and the connection’s permissions. ### Response Hub data - **No access** — the agent cannot see collections, respondents or submissions. - **Read-only** — the agent can inspect collections, submitted responses, reviews, communications and audit history. - **Changes require approval** — Collection programme changes need your recorded approval in Builder. - **Changes allowed automatically** — changes may run within your current role and the connection’s permissions. ### Data Rooms - **No access** — the agent cannot inspect room content or participants. - **Read-only** — inspect permitted room metadata, people, groups, activity and access explanations. - **Changes require approval** — permitted room changes need your recorded approval in Builder. - **Changes allowed automatically** — permitted changes may run within current casework rights, room assignment and the connection’s permissions. Nothing is selected by default. Govform checks both the connection grant and the person's current library role on every call. If that role changes or is removed, the connection immediately follows the new access. This makes it possible to let an agent improve a form without exposing live respondent data, let an operational agent triage submissions without access to unrelated form designs, or give an audit agent read-only access to selected areas. ## Ways to connect **Interactive OAuth** is recommended for people using an agent directly. Connect the MCP client to: `https://app.govform.com/builder/mcp` The person signs in to Govform, selects libraries, then separately chooses form-design, Collection programme and Data Rooms access for each one. **API-key MCP** is designed for controlled server-side integrations. Its endpoint is: `https://app.govform.com/builder/libraries/{libraryId}/mcp` API key permissions separately control form reads, form writes, deployments, Response Hub reads/writes and Data Rooms reads/writes/content. The tool catalogue only includes operations allowed by that key. ## Response Hub tools Read tools list services, collections, cohorts, assignments, immutable submitted response versions, reviews, communications, audit events and applied form-revision metadata. Write tools create or update services and collections, change collection lifecycle, apply saved forms, manage cohorts and assignments, stage and apply rosters, and perform review actions. Creating a collection also requires form-write access. Applying a collection form also requires deployment access. These extra checks prevent Response Hub access from becoming an indirect route to unrelated form-design changes. `update_programme_collection` changes draft Collection settings. A name change updates `Collection.name` only; it does not rename the managed form (`Form.formName`), save a form revision or rename an applied/deployed form. ## Collection review settings `get_programme_review_settings` reads the saved review settings and revision metadata for one Collection form; it needs both Collection and form-design read access. `update_programme_review_settings` saves `responseHubReviewRequired`, `responseHubReviewClaimRequired` and `responseHubReviewAllowChanges` using string values `"true"` or `"false"`, plus `responseHubAnswerChangeHistory` using `off`, `fromStart` or `afterSubmission`. Supply the read result's `formSsId` as `expectedSsId` and at least one setting. Omitted settings are preserved. It requires write access to both areas in the same library and respects both approval policies. Stale revisions and closed/purged Collections reject saves. Saving does not apply or deploy the form. Use `apply_programme_form` separately and complete its confirmation. Ordinary form tools still exclude managed Collection forms. See [the request and response contract](). Require review defaults off for new submissions; require claiming defaults on. When the applied Collection's `reviewClaimRequired` is false, `act_on_programme_review` can accept, return or add a comment without claiming an available response. Other reviewers' claims and held-review eligibility still apply. Claiming changes also affect existing available reviews after application. Programme create/update tools also accept optional `description` for Purpose (up to 500 characters). Omit it on update to preserve it, or send an empty string to clear it. Programme defaults apply to future Collections; partial message updates preserve unspecified templates. ## Safety boundaries - Every operation is restricted to the selected library. - Response Hub records are also restricted to one data collection service, collection and environment. - Read-only grants cannot invoke mutating tools. - Form-design access does not imply Response Hub access, or the reverse. - The signed-in person's current Govform role remains the upper limit for interactive MCP. - Applying a collection form to QA, Staging or Production returns a human approval step. - Submitted Response Hub versions and audit records remain immutable. - Tools identify read-only, destructive and externally visible operations for MCP clients. Treat agent access as sensitive. Start with read-only access, select only the libraries and areas needed, inspect planned changes, and grant full access only to workflows that are understood and supervised. ‍ ## Work from an AI client For connection steps, examples of permitted workflows and the relationship to Darcy, see [Connect AI clients with Govform MCP](). ## Use REST without an MCP client Applications can also list services with confirmed per-environment `publicationStatus` and read metadata, field summaries, full Builder definitions and deployment history through ordinary REST endpoints. See [List services, metadata and form schemas]() for API-key permissions and examples. These calls use the Builder host, while current deployed-version checks use the target QA or Production host. ## Connection discovery, tokens and evidence links The [API endpoint index]() lists the OAuth discovery, client registration, consent, token and revocation paths. MCP clients should discover these endpoints and use the normal OAuth flow rather than a library API key for interactive OAuth. Authenticated GET /builder/mcp supports the MCP transport; POST /builder/mcp carries protocol requests using the OAuth bearer token. POST /builder/libraries/{libraryId}/mcp is the library API-key channel. The connection advertises its supported tools and schemas; do not assume a tool from another release is available. Collection programme response versions and exports can return authenticated download links under /builder/libraries/{libraryId}/mcp/response-hub/collection-programmes. File, Bulk Data and export-part links require the OAuth token and the selected library's Collection programme read access. Stream their bytes rather than treating them as JSON MCP tool responses. Library API-key integrations use the corresponding REST download endpoints instead. User portal operations also configure navigation labels, Liquid content and card templates, activity table columns and status display labels. Portal deployment remains separate from applying library styles. For ordinary HTTP integrations, see the [Darcy REST catalogue and tools]() and [User portal API](). ## Test disposable journeys When advertised by your connection, `testJourney` tests routes, validation, actions and completion against the latest saved Builder service without a browser session. Describe inputs and mocks, then run scenarios with assertions. Results identify the tested saved snapshot and separate execution status from the test verdict. See [test journeys through MCP and the API]() for endpoints, access, examples and limits. ## Actions Log tools `search_actions_log` searches operational metadata in one library/environment; `get_actions_log_entry` reads a selected event’s retained diagnostic text. Defaults are the last 24 hours and 20 metadata rows, with a maximum of 50 rows and a 31-day search window. Diagnostic text defaults to 6,000 characters and is capped at 16,000; follow explicit continuations only when needed. OAuth requires read scope, selected form-design consent and a current library administrator role. API keys require `apiActionsLogRead`. Disabled audit viewing blocks both. Agent connection authentication applies without a separate browser MFA step for each read. These tools can expose retained integration request/response fragments, so administrator log access is distinct from ordinary design reads. No submission or complete definition is fetched. An assistant can ask you to perform a QA test, then correlate the service, time and reference with authentication/API/integration results. It should report missing or simulated evidence as unverified. Each call uses 1 API unit. See [Actions Log guidance]() for arguments, examples, retention and the user-performed QA workflow. ## Review current answers and saved changes The managed Collection settings tools support `responseHubReviewAllowChanges` and `responseHubAnswerChangeHistory`, both off by default. Read settings, save with `expectedSsId`, and apply the managed form separately. New responses inherit these options. `get_programme_answer_changes` reads a bounded Change log page: supply `responseId`, optional zero-based `page` and optional `changeId`, with the usual programme, Collection and environment selectors. Omit page for newest entries; decrease the returned page number for older entries. History covers page and committed attachment checkpoints, not every automatic or external mutation. Earlier files have authenticated download links. `get_programme_review` returns current saved answers and `expectedAnswers` for a live review. Pass this object unchanged to `act_on_programme_review` with `action: accept`. Acceptance rejects intervening answer changes; `acceptanceFailure` explains when the latest answers cannot be accepted yet, and a required caseworker form must be submitted first. Use `action: editIssue` with `issueId`, `expectedUpdatedAt`, `respondentMessage` and optional `internalNote` to amend live feedback. Existing claims, scopes and approval choices still apply; Return for changes is unavailable during live review. ## Staff sign-in and respondent authentication guidance Use `getGovformsProductDocumentation` with `topics: ["accounts-and-access"]` for Builder staff Microsoft/Google sign-in, administrator consent, required scopes and identity claims, library permissions and QA’s separate Govform and service access checks. No service ID is required; the connection’s library permissions still apply. The same guidance is available to Darcy. See [Library authentication settings]() for the staff/respondent distinction and external QA tester access. ## Comment on the whole form or an individual field On the review screen, use **Comment on the whole form** for the overall comment sent with **Return for changes**. It is required when returning a response, but not when accepting it. The rich editor opens in **Text** mode by default. Use its toolbar for formatted text; the comment is stored as Markdown and displayed with formatting to staff and the respondent. For a particular answer, go to **Field comments**, expand **Comment on an individual field**, choose the **Answer**, write your comment and select **Add field comment**. Repeat for other fields. Field comments are plain text and appear beside the relevant answers and in the summary. The whole-form return comment and field comments are shared with the respondent. Internal notes are visible only to staff. In standard review, the respondent sees the comments when you return the response. Ordinary Form responses send no automatic return email; Collections send their return email. With **Allow changes during review**, staff can add or edit field comments and respondents see them on their next visit, without an email. Return for changes and its whole-form comment are unavailable in this mode. Ordinary live-review field comments also support replies. Standard reviews and Collection programmes have no replies. Existing REST/MCP names remain unchanged for compatibility: `addIssue`, `editIssue`, `issueId`, `issues`, `list_programme_review_issues` and the `/issues` endpoint refer to comments. Use `reason` for the whole-form return comment in Markdown (up to 5,000 characters); `target` and `respondentMessage` identify a plain-text field, bulk-data row or cell comment. `internalNote` stays private. Each `respondentMessage` and `internalNote` can be up to 5,000 characters. These Collection tools do not operate ordinary Form responses; ordinary casework uses the browser. ## Staff support preparation Interactive OAuth connections signed in with an exact `@govforms.co.uk` or `@govform.com` staff address can inspect support tickets across libraries with `mcp:read`. Changes additionally require `mcp:write`. Customer connections and library API keys cannot use these tools. AI can use `note_support_ticket` for private notes and `update_support_ticket` to save `triageSummary`, `draftReply` and preparation stages `triaging`, `preparingReply` or `withStaff` without individual Builder approval. Supply the ticket `id`, freshly read `expectedRevision` and `authorKind: "ai"`. Reread and reassess after a revision conflict. Internal notes, findings and drafts are hidden from customers; the saved draft pre-fills the existing staff reply composer for human review and sending. `reply_support_ticket` sends a customer message and still requires individual Builder approval. Updates to assignment, labels, status or other workflow stages also require approval, even when combined with a draft or triage findings. For these changes, supply `approvalDescription`; on `CONSENT_REQUIRED`, ask the initiating user to approve the exact request in Builder and confirm, then retry identical arguments with `approvalToken`. Approval expires after 24 hours and permits one retry. Saving a draft does not send it, return the ticket to the customer or start an automatic closure countdown. The same rules apply to `POST /builder/api/support/system` using the staff OAuth bearer token and `{ "operation": "note|update|reply", "args": { ... } }`. Use one operation per request. Human support users can review the prepared draft and select **Send reply**, with **After sending** set to **Await customer reply** in Support administration. ## Temporary demos without an account The separate `POST /builder/try/mcp` connection creates browser demos that expire after 14 days, using a private management token for later changes. It grants no access to existing libraries or deployment. See [Create a temporary demo with an AI client]() for the tools, settings and limits. ## Concurrent form-definition saves For MCP form-definition changes, `expectedSsId` is checked against the current saved revision after Govform acquires the existing form lock. If another save completed while an edit was being prepared, the change is rejected with `MCP_FORM_REVISION_CONFLICT` before anything is saved. Read the latest definition and reconstruct the edit before retrying. This applies to full-definition saves, Darcy MCP edits and temporary demo edits. Existing REST calls that omit a revision precondition retain their current behaviour. ## Approved admin submission investigations Govform staff and configured platform administrators can investigate a specific library’s submissions through the interactive OAuth connection. Customer library administrators and library API keys cannot use these operations. Every search page and retrieval needs its own one-use Builder approval confirming permission from that customer’s GDPR data controller for the exact records and purpose. | MCP tool | OAuth POST endpoint | Result | | --- | --- | --- | | `search_submission_user_data` | `/builder/api/admin-submission-data/search` | Current submission metadata; default 20, maximum 50 records. | | `get_submission_user_data` | `/builder/api/admin-submission-data/get` | Current journey answers, action results, state and caseworker source linkage. | | `get_submission_version` | `/builder/api/admin-submission-data/version` | One retained ordinary response version, submitted answers and captured caseworker source linkage. | All calls select `org`, `formId` and `environment` (`qa`, `staging` or `production`). Retrieval also requires `submissionId`. Version retrieval accepts optional positive `versionNumber`; omit it for the latest retained version. Missing evidence returns not found: it is never reconstructed or replaced by current answers. Collection response versions use the Collection programme operations. Files are metadata only; configured Secrets remain masked. Supply `approvalDescription` naming the library/customer and purpose. On `CONSENT_REQUIRED`, present the returned `approvalUrl`, wait for the admin to approve in Builder and confirm, then retry the identical request with `approvalToken`. Early access OAuth uses `/builder/early-access/api/admin-submission-data/{search,get,version}`. These reads do not authorise actions, edits or deployment. Darcy provides matching approved admin sidebar tools. Its Builder release check reports Main or Early access separately from the response data environment. A selected Staging environment does not establish that Early access Builder is switched on. ## SharePoint upsert mapping checks Saves of an existing service through REST, MCP and Darcy check linked SharePoint lookup and update column mappings. Each update value is written to the lookup list column with the same name, so an update may list only the columns it changes; unlisted columns are left unchanged. Saving an edited update adds new list columns to its lookup without removing any. Conflicting, ambiguous or unknown mappings and removal of non-empty mapped columns return HTTP 400 with `SHAREPOINT_LIST_MAPPINGS_INCONSISTENT` and a review message. Refresh and review the linked list settings in Builder before retrying. Authoring tools do not contact SharePoint to refresh columns or run Automap. Unrelated edits to older services remain possible; deployment checks the exact version selected. Saving and deploying remain separate operations, with existing permissions and approval requirements. ## Data Rooms Retained rooms and files have dedicated REST and MCP operations, with Data Rooms consent separate from form designs and Collection programmes. Current casework rights and room assignment still apply. Room changes save immediately in the selected environment; Library settings retain their normal apply/deploy lifecycle. Binary transfer uses authenticated browser or REST streams. See the [Data Rooms API](). ## Ordinary response comment conversations Ordinary Form responses with **Allow changes during review** support field comment history and staff/respondent replies in the browser. Standard reviews and Collection programmes have no replies. Public REST, MCP and Darcy have no ordinary-response reply/history operation, and Collection review endpoints cannot operate ordinary responses. See [field comment history and replies]() for the workflow, statuses and permissions. Review and answer-history settings still use their existing authoring APIs and separate save/deploy or save/apply steps.