Connect AI clients with Govform MCP
Govform MCP lets a connected AI client inspect and manage the platform through structured, permission-aware tools. Use it when you want to work from an external assistant or build a controlled agent workflow.
How MCP fits alongside Darcy and the REST API
Darcy is the assistant inside Builder. MCP, the Model Context Protocol, exposes tools and guidance to an external client, which supplies its own AI experience. The REST API serves integrations that call defined endpoints directly.
A connected client can discover the tools available to its connection, read product and model guidance, and invoke authorised operations. The client's tool catalogue determines what it can actually do; it is not a promise that every Darcy interaction is available externally.
Connect interactively
For a person working in an AI client that supports MCP with OAuth, connect to:
https://app.govform.com/builder/mcp
- Add the MCP server in your client.
- Sign in to Govform through the connection flow.
- Select the libraries needed for the task.
- Choose form-design access and Response Hub data access separately for each library.
- Review the discovered tools and begin with an inspection task to confirm the connection.
No library access is selected by default. The connection grant and your current library role are checked on each call. If your role changes, the connection follows the new permissions.
Choose access for each area
| Grant | Form designs | Response Hub data | Data Rooms |
|---|---|---|---|
| No access | The client cannot inspect service designs. | The client cannot inspect collections, respondents or submissions. | The client cannot inspect room data. |
| Read-only | Inspect designs and deployment status. | Inspect authorised operational data, responses and review history. | Inspect permitted room metadata, access and activity. |
| Full access | Make permitted design changes and prepare deployments. | Perform permitted collection, assignment and review operations. | Make permitted room changes, with the selected approval policy and current casework rights. |
The areas are independent. You can let a client improve a service design without exposing live respondent data, or give an operational client the Response Hub access needed for its workflow. Full access remains limited by your role and the operation's requirements.
What clients can do
Depending on the connection and available tools, clients can find libraries, services and patterns; inspect service structure; create and update designs; read deployment information; and prepare publication steps. Guidance resources describe the platform model, field types, Liquid and supported integrations.
With separate Response Hub permission, clients can inspect authorised submissions and reviews, manage collection configuration and assignments, or perform supported review actions. Additional design or deployment permissions apply where an operation also changes or publishes a collection form.
A publication preparation result or browser approval link is not a completed deployment. Complete the required human step and check the returned status. Submitted Response Hub versions and audit records remain protected from rewriting.
Use API-key MCP for server integrations
For a controlled server-side connection, use the library-scoped endpoint:
https://app.govform.com/builder/libraries/{libraryId}/mcp
API-key permissions separately govern form reads, writes, deployments, Response Hub access and Data Rooms access. The key's tool catalogue includes only permitted operations. Keep the key on the server and use the authentication requirements documented for the endpoint.
Plan usage and review changes
MCP tool calls use API units according to the operation they run. Read the Govform MCP capabilities reference for unit tiers, transport details and the wider tool coverage.
For a design task, give the client a clear brief and inspect its changes in Builder and User view. For an operational workflow, choose the precise library, data area and permissions it needs, and review actions that affect respondents or published services.
See Govform API for direct integrations and Response Hub API for operational data access.
Check a QA integration test with your assistant
An authorised assistant can ask you to perform a defined QA test, wait for your confirmation and use search_actions_log followed by get_actions_log_entry to inspect relevant authentication, API and other integration outcomes. Give the service, test time and submission reference when available. Darcy supports the same workflow inside Builder. These reads require library administrator OAuth access or the dedicated API-key permission and enabled audit viewing.
Search returns compact metadata; diagnostics are read separately in bounded sections. Simulated or missing evidence does not verify a real integration, and a successful recorded call does not establish delivery or downstream processing. See Actions Log guidance for the full workflow and access rules.
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.
Prepare support tickets for staff review
Govform staff connections can add private notes, save internal triage findings and prepare a complete draft reply without individual Builder approval. The draft appears in the support staff reply composer for a person to review, edit and send. Sending a customer reply or handing the ticket back to the customer still requires human approval. These staff tools are unavailable to customer connections and library API keys. See Staff support preparation for the tools and permissions.
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.
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.
