Set up an MCP connection

Output.Rocks exposes a curated set of documentation, configuration, process, and testing functions through MCP. The production endpoint is:

https://app.output.rocks/api/mcp

For the test environment, replace the endpoint in the examples below with https://app.staging.output.rocks/api/mcp. Sign in to Staging for that connection; production and Staging connections are separate.

Authentication uses OAuth 2.1 in your browser. Use an active, non-delegated Output.Rocks browser session and approve only the scopes you need:

• mcp:read for documentation, configurations, processes, test renders, and simulations
• mcp:ai in addition for AI error analysis
• mcp:write for change proposals that are applied only after your browser confirmation

An MCP connection cannot modify business data directly. An allowed change first appears in the app as a proposal that expires after 30 minutes and includes a before/after diff. Deletes and security-sensitive fields are excluded.

Availability and validation status

The production release of September 11, 2026 covers the file, preview, configuration, process and report/archive functions available at that time. Historical practical Codex testing covers that scope.

Final Codex acceptance of the extended template workflow, including direct text changes, multiple cases, full visual review and recovery, remains open: 0 of 5 consecutive complete runs on the final build, as of October 2, 2026. The individual September 16 results remain historical evidence and do not count towards the new series. The installed native Codex app version is 26.930.21537; final acceptance with this client is pending.

Independent Claude acceptance is tracked in OR-244 and does not block Codex acceptance or production release. Its new series also starts at 0 of 5; historical Claude results remain in OR-188. Automated tests and an available staging deployment do not replace client acceptance. Production approval and live verification remain separate steps. Use get_mcp_context to verify the selected environment; this guide does not enable features.

GitHub Copilot in VS Code has not been practically tested. Other Copilot products are outside this guide's scope. The setup instructions below do not establish successful client acceptance.

Claude and Cowork

Open Customize > Connectors > Add custom connector (under Settings in some interfaces). Enter a name and the production endpoint https://app.output.rocks/api/mcp. If offered, choose Authentication: Always required and No client ID – register automatically. No custom client secret or additional headers are required.

Select Add, then Connect, and complete the Output.Rocks browser sign-in. Enable the connector for the conversation or Cowork task. In managed organizations, an owner may need to add it first. See Claude's remote connector guide.

Claude Code

claude mcp add --transport http output-rocks https://app.output.rocks/api/mcp

Then open /mcp in Claude Code, select output-rocks, and complete the browser sign-in.

Codex

codex mcp add output-rocks --url https://app.output.rocks/api/mcp
codex mcp login output-rocks

Complete sign-in and scope approval in the browser. Start a new Codex session and use /mcp to check that tools loaded. codex mcp get output-rocks only shows configuration. A successful tool call, such as documentation search, verifies access.

In the observed Codex app, servers appear under Plugins > MCPs (or Settings > MCP servers, depending on the version). Add an HTTP server there. If no sign-in option is shown, use the CLI sign-in steps above. The CLI and app share MCP configuration on the same computer. See MCP in Codex.

GitHub Copilot in VS Code

Create .vscode/mcp.json in your project:

{
  "servers": {
    "output-rocks": {
      "type": "http",
      "url": "https://app.output.rocks/api/mcp"
    }
  }
}

Start the server through VS Code's MCP management, confirm trust and follow the requested OAuth browser sign-in. Open Copilot Chat and enable the Output.Rocks tools in the tool picker. This guide covers GitHub Copilot in VS Code; other Microsoft Copilot products are outside this integration. See Managing MCP servers in VS Code.

Use the extensions in production

The historically released extensions require additional permissions. Sign in again and grant only the scopes you need. The pending validation status above applies to the new template workflow. Example for template editing with Codex:

codex mcp add output-rocks --url https://app.output.rocks/api/mcp
codex mcp login output-rocks --scopes mcp:read,mcp:write,mcp:files,mcp:data

Explicitly approve additional mcp:process-data for process diagnostics/actions or mcp:reports-archive for reports/archive access. Select only the permissions needed. In Claude/Cowork and VS Code, likewise configure the server with the production URL. Additional scopes require new OAuth consent; existing connections are not expanded automatically.

Example requests after signing in:

• “Move the address block of template xxx to fit the existing Binect overlay. Show original and draft with identical test data, then create an approval proposal.”
• “Reduce table row spacing on page 2 of template xxx. Check every page with short and long test data, including headers and footers.”
• “Find all blocked document processes with a proven webhook failure. Propose retrying this fixed selection at the failed step using the original configuration.”

Small text changes use the draft text tools below. General layout changes require a DOCX editor and the protected file dialog. Output.Rocks supplies context and previews and renders through the existing Template Editor. Browser approval is required to save a template or execute a process action. Afterwards, read back the saved version or inspect each job outcome. Close temporary editing sessions and previews when finished.

Archive and sub-clients are optional tenant modules. OAuth consent alone does not enable them: access and sub-client assignments require the enabled module and sufficient user permissions. An empty result does not prove module availability.

Additional file and content access

Use https://app.output.rocks/api/mcp and explicitly approve mcp:files for files or mcp:data for complete configuration and test data during a new OAuth sign-in. These contents may include personal data. Existing connections do not receive additional permissions automatically.

• open_template_file retrieves the DOCX for an exact template version ID.
• create_artifact, upload_artifact_chunk, and finalize_artifact transfer a temporary DOCX draft or PDF overlay and check its SHA-256. Damaged or encrypted PDFs are rejected. Limits are 10 MiB per file, 64 MiB unpacked, and 2,000 archive entries.
• read_artifact_chunk returns up to 16 KiB as base64. Follow nextOffset until null, then verify the checksum of the complete file.
• get_entity_content returns complete permitted JSON content in chunks. Supply sha256 on subsequent reads; concurrent changes cause a conflict. Secrets, binary and internal fields, and nested integration connections remain excluded. Explicit mcp:data consent permits email address fields and plain configuration identifiers. For templates, images, PDF overlays and email attachments, this includes detail metadata such as filename and comment; get_entity keeps its existing compact response.
• release_artifact removes only this connection's temporary file.

Drafts do not change active templates. Finalized files are immutable; further edits require a new artifact. Access ends when the connection expires or is revoked, at the latest after 23 hours. Automatic cleanup runs every 15 minutes. Each user and tenant may hold up to 100 temporary files totaling 64 MiB.

Render template drafts with the Template Editor

The Template Editor role and mcp:read, mcp:files, and mcp:data permissions allow draft editing without activating a template:

1. Check the environment, scopes and prerequisites with get_mcp_context. Select the exact template version with list_entities; resolve duplicate identifiers by brand and sub-client. prepare_template_edit(templateId) shows the version, effective preview brand, assignments and named test data. Narrow the selection with testDataSearch, page, limit and pagination.nextPage. Test data is not assigned to a template; explicitly resolve ambiguous candidates.
2. Start begin_template_edit with templateId and one to five named testCases. Each case has exactly one source: saved testDataId, a JSON object or array as testData, or finalized testDataArtifactId. Case example and selection rules. The existing single-source arguments remain available, with testDataName for temporary data. Data stays in the edit; no permanent test-data record is created.
3. Read the returned context. For contextAccess, read get_template_edit_context chunks until nextOffset: null and verify size and SHA-256. get_template_syntax supplies syntax guidance. Selection and test data remain immutable; all stored case data together must fit within 10 MiB.
4. Use find_template_text and replace_template_text for small text changes with explicitly selected matches and the source hash. For layout changes, download the original through the file dialog, edit it in a DOCX editor, and upload the draft. get_artifact_status must report ready: true for that draft.
5. Start compare_template_edit with editId, finalized draftArtifactId and a new UUID requestId. Omitting caseIds compares every case. get_template_comparison reports progress and results. Original and draft use identical fixed data and reference time. The existing single-case render_template_edit path remains available.
6. After successful rendering, use get_template_preview_info and get_template_preview_page to inspect all pages of every selected case. Test first stops at the preview. Only an explicit save request leads to propose_template_update with editId, draftArtifactId, comparisonId and a concrete summary. Visually review and explicitly confirm every case at the approval link; see browser approval. Read back the saved version afterwards. Keep the edit open until the decision.
7. close_template_edit removes the original copy, managed text drafts, preview PDFs, temporary overlays and any copied recovery inputs. Always clean up externally uploaded DOCX drafts and JSON sources separately with release_artifact, including after their use in a comparison.

Rendering neither saves nor activates a template. Changed sources or configuration require a new comparison or edit. Limits are ten open edits per user and twenty previews per edit, plus general file and expiry limits. Larger contexts are read in 16-KiB chunks. Secrets are removed from test data too.

Change text directly in a template draft

find_template_text searches exact, case-sensitive searchText with editId. Omitting sourceArtifactId selects the original; supply the latest draft ID for subsequent changes. Follow pagination.nextPage to inspect all relevant matches. Each match provides matchId, document part, paragraph, context and canReplace with a possible rejection reason. Positions use UTF-16 code units; copy the opaque match IDs unchanged instead of calculating positions yourself.

replace_template_text requires editId, a new UUID as requestId, sourceArtifactId, the returned sourceSha256, the same searchText, and an explicit replacements selection containing matchId and replacementText for each occurrence. There is no blanket replace-all operation. Only selected matches change; replacement text inherits formatting from the first matched run. Fields, placeholders, tracked changes, structural boundaries and overlapping matches are rejected explicitly.

The result contains a new finalized draftArtifactId, its hash and a change summary. Source bytes remain unchanged. Rendering, visual inspection and approval are separate explicit steps in the workflow above; text replacement does not start them automatically.

Reusing a request ID with identical input returns the same draft. Different input or another operation under that ID causes a conflict. Timeouts and interrupted requests are never retried automatically: inspect existing artifacts or close the edit. A deliberate new attempt requires a new ID. A changed source hash requires a fresh search first.

Limits: 50 matches per page, 1,000 selected replacements and 64 KiB for all MCP input arguments combined per call. Text changes reject new request IDs after 100 shared edit requests; comparisons do so after 50. Search text is limited to 4,096 UTF-16 code units; each replacement to 65,536. Replacement text must be single-line text without tabs or control characters. The DOCX limit remains 10 MiB. Connection, role, tenant and subclient permissions and expiry are checked again. Derived drafts remain bound to their sources; retain source artifacts until completion. close_template_edit also removes unrendered and partially generated text drafts.

Preview pages and overlays

get_template_preview_info accepts editId and pdfArtifactId and returns the page count and every page size in points. get_template_preview_page additionally accepts a 1-based page and returns a standard MCP image for visual inspection. Use page 2 to check its table.

Optionally choose either a saved overlayId (resolve it with list_entities, entityType: "pdf_overlays") or a finalized temporary PDF overlayArtifactId. Never invent a Binect overlay or its dimensions. The existing Template Editor comparison places the matching overlay page at 50% opacity, scaled to the base page size. Missing overlay pages return overlayApplied: false.

Limits: 200 PDF pages, 14,400 points per page edge, 1,600 pixels on the longest image edge, 20 temporary overlays per preview. Oversized images or PDFs that exceed processing limits fail explicitly. Closing removes used temporary overlays. The overlay is applied only to the returned image; original PDF, draft PDF and DOCX remain unchanged. Compare both versions with the same overlay.

Manage connections and proposals

Open Integration > MCP connections to see your own connections, their scopes, and pending change proposals. You can revoke a connection immediately or approve or reject a proposal after reviewing its diff. If the target changed after the proposal was created, the proposal becomes stale and is not applied.

Links from the OAuth dialog open the relevant approval directly. Confirmation is possible from any active, non-delegated browser session belonging to the same user and tenant. The original MCP connection and its bound browser session must remain valid.

Never share access or refresh tokens. Cancel approval if the sign-in page is unexpected, the redirect address is unfamiliar, or the requested scopes are broader than intended.

Approve a reviewed DOCX in the browser

The connection also needs mcp:write and permission to edit the exact template. propose_template_update binds approval to the rendered draft, its checksum, original version and test data. A different draft requires a new proposal. Optionally supply one saved overlayId or temporary overlayArtifactId; an immutable overlay snapshot is used for comparison and never added to the DOCX.

The browser shows the original version, description, complete context, test data and both previews with page navigation. Approval uses existing template versioning; activation and scheduled versions follow the same rules as the Template Editor. Rejection saves nothing. Repeated approval does not create another version. Concurrent changes, removed files, expiry and revocation prevent saving. Proposals expire after 30 minutes.

An unknown save outcome blocks another save. Use Check save status; the change remains accessible through its link after reloading. A connection error does not prove that nothing was saved. There is no automatic retry.

Explicitly approve every comparison case

For multiple test cases, pass the completed comparisonId to propose_template_update. The proposal binds every case selected in that job, the exact original/draft PDFs, the draft, fixed reference date, and resolved dependencies. Approving a smaller subset of the same comparison is not supported. Failed, partial, or stale comparisons cannot be proposed or applied.

The existing browser dialog provides a named case selector and per-page original, draft, and genuine transparent overlay (50%). Added and removed pages are marked explicitly. Individual views show page dimensions; the overlay scales the draft to the original page. Recorded MCP text edits are summarized. Externally or partly externally edited DOCX files explicitly state that a complete semantic diff is unavailable.

Open and inspect every page of each case, then select “I have visually reviewed every page of this test case.” Applying becomes available only after every case has been explicitly confirmed. Fully loaded pages remain recorded while the context is still loading. Case confirmation and applying remain blocked until the entire context has loaded. Context, page or image loading failures invalidate previous review evidence. A changed comparison fingerprint requires fresh review; switching cases cannot bypass it. Loaded images and successful rendering alone do not constitute visual review. The case selector only navigates; it does not reduce the approval scope. The server requires confirmation of the exact comparison and full case set, and rechecks current rights, sources, PDFs, and dependencies immediately before writing. Subsequent changes require a new comparison and proposal. Existing single-case proposals remain readable; rejection and repeated confirmation retain their existing behavior. This flow does not automatically activate a template or approve a production release.

Editing configurations and versions

propose_configuration_change extends browser-confirmed editing to brands, sub-clients, document templates, standard values, template components, email templates, standard email templates, test data, custom mappings, validators, charts, QR codes, images, PDF overlays, form configurations and email attachments. Its field schemas describe the supported assignments, activation dates and files. The reading tools also accept email_attachments. list_entities returns pagination with nextPage; when the source provides no total count, the final continuation page may be empty (nextPageMayBeEmpty).

The connection needs mcp:read, mcp:write, mcp:data and the corresponding UI permissions. Sub-client management additionally requires an administrator in the main tenant with the sub-client module enabled. User, role, secret and integration administration are excluded.

• operation: "create" creates a proposal only. operation: "update" requires the exact entity id. Renaming and general deletion are excluded.
• File fields are named fileArtifactId, or imageArtifactId for images. Upload and finalize the file using the artifact tools first; this requires additional mcp:files consent. Images accept PNG/JPEG, overlays accept PDF and document templates accept DOCX. create_artifact lists the accepted attachment formats.
• The templates and emailTemplates assignments contain template identifiers. The affected templates, their state and permissions are checked again on approval. Concurrent changes invalidate the proposal.
• Creating a document template also requires testDataId. The existing Template Editor generates a preview without saving a template. Visually inspect the PDF and get_configuration_preview_page, then open the approval link. For DOCX changes to existing templates, continue using the editing workflow above with propose_template_update.

If the field object exceeds the 64 KiB tool input limit, upload it as a UTF-8 JSON artifact and pass fieldsArtifactId instead of fields (maximum 10 MiB). Large proposals point to get_pending_change_content. Follow nextOffset until null, passing the returned sha256 on continuation requests. Fields and diffs are returned completely rather than silently truncated.

propose_configuration_version offers restore for an exact version ID and cancel for a future scheduled version. restore optionally accepts activeFrom as a timestamp including its time zone. Both actions require browser approval, use the existing versioning rules and refuse execution if the version history has changed since the proposal was created.

Diagnose processes

search_processes reads document, email, XML and data collector processes as well as rendering requests. It requires mcp:read, explicit mcp:process-data consent and the permissions of the corresponding UI view. Sub-client boundaries remain enforced. The existing process tools remain available unchanged.

Example request: “Show blocked document processes with a proven webhook failure. Explain one result using its workflow log.”

• Set processType to document, email, rendering_request, xml or data_collector. The tool describes the supported filters for each type.
• filters: {"failureCategory": "webhook"} requires a failure captured during a webhook operation and a matching current blocked state. An assigned webhook or a text match is insufficient.
• Structured failure capture starts with this release. Older errors without this evidence are not automatically classified as webhook failures. List blocked processes without failureCategory to inspect their logs.
• Follow pagination.nextPage until null. If the UI does not provide a total, totalItems remains unknown. nextPageMayBeEmpty explicitly indicates when continuation may return an empty page.
• get_process_diagnostics reads a specific process state and failure evidence. get_process_content provides complete metadata, workflow_log or permitted payload sections. Data collector processes have no payload section of their own.

Large sections are transferred as base64 JSON chunks. Follow nextOffset until null, echo sha256 on continuation requests and verify the assembled file. If the content changes, restart from offset zero. Secrets, authentication headers, internal paths and integration connection details are excluded. Overview error messages may be shortened, as indicated by messageTruncated; the full workflow log remains separately readable.

These diagnostic tools perform no process actions. Use the browser-confirmed workflow below for actions.

The new mcp:process-data permission requires a new OAuth consent. Previously granted mcp:data does not include process payloads.

Process actions and fixed batches

propose_process_action creates a proposal for explicit process IDs. It requires mcp:read, mcp:process-data and mcp:write.

Example: “Retry all document processes with a confirmed webhook failure, using the original configuration and continuing at the failed step.”

1. Follow every page of search_processes with filters.failureCategory: "webhook". Inspect the causes and retain exact IDs.
2. Propose processType: "document", action: "retry", reason: "webhook_failure", ids and a meaningful summary. resolutionMode defaults to original; choosing retry explicitly resolves configuration again.
3. Open approvalUrl. Review the action, count, reason, each ID and its state, and possible recalculation or redelivery. Apply change schedules the batch; rejecting it changes no process.
4. Read the returned job (result.entityId) through get_process_job. Follow nextPage to read every individual outcome.

Each proposal contains at most 500 IDs. Explicitly split larger selections into separate batches. Later matches are not added. Changed processes, missing permissions or revoked connections cause items to be skipped. Confirming twice creates no second job.

Email reprocessing reuses the existing bounce workflow. It creates a new rendering request with current configuration resolution; optional parameters match the UI. It does not overwrite the source email. Resending may cause another delivery. Request and XML corrections are described as dedicated actions below.

Job outcomes distinguish queued, running, successful, skipped and failed. Successful means the workflow invocation completed, not proof of external delivery. Reprocessing returns the newly queued request ID. An uncertain worker interruption is not blindly repeated: inspect the process before creating a new proposal. Normal worker retries do not prepare an approved action again. Unaffected items may continue.

Correct requests and e-invoices

These propose_process_action actions each require exactly one ID, mcp:read, mcp:write, mcp:process-data and browser approval. Business data stays unchanged until approval. The existing simulate_rendering_request tool remains compatible; use simulate_request for an approved correction simulation.

For request correction/simulation, options supports renderData, metadata, templateIdentifier, format, externalId, webhookIdentifier, mailServerIdentifier and comment. Omitted fields retain their source values; null or empty optional text clears that field. For XML correction, options.payload contains the complete JSON invoice object, not XML text. Omitted profile/skipValidation values are inherited as in the UI and shown in the proposal. Secrets and embedded binary data are rejected.

Example proposal (replace 12345 with the previously resolved request ID):

{
  "processType": "rendering_request",
  "action": "simulate_request",
  "ids": [12345],
  "summary": "Check the corrected invoice amount before reprocessing",
  "options": { "renderData": { "invoice": { "total": "123.45" } } }
}

renderData replaces the whole payload: first read it completely with get_process_content and retain unchanged fields. Large options can be uploaded and finalized as a JSON file through the existing artifact tools. Supply optionsArtifactId instead of options (additional mcp:files consent, maximum 2 MiB JSON). The proposal freezes a copy of the validated content; edits require a new proposal.

Browser review shows the ID, baseline state, action and full parameters. Regeneration/remapping may resume a held document and trigger further delivery. A new request ID initially means queued; inspect that request's eventual outcome.

Read job state with get_process_job, then retrieve the complete permitted simulation result with get_process_job_content using jobId and processId. Follow nextOffset with the unchanged sha256 and verify the assembled checksum. Before/after data and resolution results are complete. Secrets, files, internal paths, integration settings and raw value-diff entries are explicitly excluded; compare dataBefore and dataAfter. Source permissions and tenant scope are rechecked when reading results.

Reports, archive and configuration transfer

These MCP extensions are available in production at https://app.output.rocks/api/mcp. Explicitly approve the additional permissions you need during a new OAuth sign-in.

Read reports and archive records

read_reports reads monthly report listings (kind: monthly), existing rendering report jobs/results (kind: rendering, optional job id), or the SLA summary (kind: sla). It does not generate new reports. read_archive lists permitted archive entries or reads an entry by id. Filters cover search, state, source, legal class, legal hold, external identifier and creation dates. Existing UI role, module and tenant restrictions still apply.

Both tools return complete permitted JSON in base64 chunks. Keep every filter unchanged and follow nextOffset with the same sha256 until nextOffset is null, then verify the checksum. Listing JSON contains pagination.nextPage; use it for the next page and restart at offset 0 without the previous hash.

open_report_file downloads the PDF for a monthly report ID; open_archive_file downloads an archive original using the existing download audit trail. Read the private artifacts through read_artifact_chunk. Each file is limited to 10 MiB. Larger or unavailable content fails explicitly rather than being truncated. Permissions are checked again for every chunk. Internal storage locations and credentials are never returned.

Export and confirm configuration imports

Administrators can export a fixed selection of 1–100 exact version IDs through export_configuration. Categories match the existing UI transfer: brands, standardValues, images, charts, qrCodes, templates, emailTemplates, emailAttachments, standardEmailTemplates, templateComponents, dataValidators, testData. Example selection: {"testData":[123]}; resolve IDs first. The default brand record is excluded. An unauthorized ID fails the selection instead of silently disappearing from the ZIP. Configurations with secrets or unassigned embedded binary data are rejected rather than silently changed during export.

Upload and finalize a configuration ZIP using the artifact tools, then:

1. Call preview_configuration_import with artifactId. Optional activation settings are active (default, active, inactive) and an ISO timestamp in activeFrom. Preview does not change configuration.
2. Read every preview chunk. Each row includes its category, zero-based index, content, file checksums and optional existingId. Conflict detection is shared with the UI importer.
3. Call propose_configuration_import with unchanged options, previewSha256, a summary and an explicit action for every preview row. Each selection object contains category, index, action: new rows allow create/skip, conflicts allow overwrite/skip.
4. Review the exact ZIP checksum, activation and fixed selection in the browser. Approval runs the existing importer and its versioning rules. Changed files or target configurations stop the import.
5. Read get_pending_change for imported, overwritten, skipped. Repeating approval does not repeat the import. Release temporary artifacts afterwards; otherwise their displayed expiry applies, at most 23 hours.

File/data access requires explicit mcp:files and mcp:data consent; import proposals also require mcp:write. Existing connections do not gain permissions automatically. General deletion, archive changes and arbitrary REST calls remain excluded.

Reports and archive require the new mcp:reports-archive OAuth permission in addition to data/file consent. Sign in again and explicitly approve reports, archive records and (with mcp:files) original document downloads. Existing connections do not receive this access automatically.

Archive access additionally requires the tenant’s archive module to be enabled. Managing or assigning sub-clients, or sharing configuration as a sub-client default, requires the sub-client module. OAuth consent does not enable either module. Module availability is checked again when the operation executes.

Brands and letterheads

For brand-aware configuration, list_entities accepts either brandIdentifier (explicit brand rows) or effectiveBrandIdentifier (including inherited defaults). get_entity_content with entityType: "brands" and section: "effective_configuration" reports inheritance and overrides across all nine brand-aware configuration types and requires data consent.

run_test_render and begin_template_edit accept brandIdentifier for shared templates. Brand-specific templates remain locked to their own brand. Editing stores the preview brand separately without changing the template assignment.

The extended propose_configuration_change tool supports layoutFileArtifactId for a brand letterhead upload and removeLayout: true for removal. Uploads require a finalized DOCX artifact and file consent. Browser confirmation, letterhead validation and versioning apply; default cannot carry a letterhead. Templates support brandLayoutDisabled. Configuration transfer includes the letterhead file, with its type, size and checksum shown in the import preview.

Diagnose missing tools and permissions

Start with get_mcp_context. It reports the actual server address, tenant and sub-client, granted scopes, enabled modules, session expiry and function prerequisites without exposing credentials. List test data with list_entities:

{"entityType": "test_data", "page": 1, "limit": 20}

Follow pagination.nextPage until null. Select ambiguous results by name; never guess IDs.

Client permission and server permission are separate. Claude/Cowork does not call tools marked as blocked in its connector settings. Check the connector selected for the conversation, its endpoint and local tool permissions. The server cannot observe these settings. In the investigated Claude failure, List entities was visible but blocked on the connected production connector; the staging connector was disconnected. This is not evidence of a missing server-side test-data function.

When comparing catalogs, read every tools/list page using nextCursor and compare the same connector and environment. Missing OAuth scopes do not hide server tools. Extension tools additionally require environment-level enablement.

Structured tool errors contain code, message, missingScopes and nextStep:

• MCP_SCOPE_REQUIRED: grant only the listed missing scopes.
• ROLE_REQUIRED: have an administrator check the named application role.
• MODULE_DISABLED: check the named tenant module or environment extensions.
• ACCESS_DENIED: check current object and sub-client access.
• CONFLICT: reload the current state; do not reuse stale proposals.
• RESOURCE_EXPIRED: start a new editing session or upload.

Signing in again does not fix blocked client tools, missing application roles or disabled modules. Invalid access tokens and OAuth authentication failures remain HTTP/OAuth errors.

For template review, follow the complete workflow above. Never manually reconstruct DOCX binaries in chat.

Choosing temporary test data

A named preview case can be supplied even when no saved test data exists:

{
  "templateId": 123,
  "testDataName": "Short sample invoice",
  "testData": { "customer": { "name": "Sample customer" }, "items": [] }
}

Replace the example ID with the exact version selected for this task. Send large integers as strings when the client could lose precision. Upload and finalize large JSON files using the existing file tools, then pass their testDataArtifactId. A scalar JSON value is not sufficient.

context.testCases contains the immutable default case for the existing single-source call; context.testData remains available as the compatible first case. Current access permissions are checked throughout editing. A draft based on a JSON artifact expires no later than its source and cannot be used after that source is released or expires. These restrictions also apply to direct downloads of derived PDF previews. Owners can still clean up the draft and its files after losing the source or access to it. Closing the draft does not delete a separately uploaded JSON source; release it with release_artifact when it is no longer needed.

prepare_template_edit changes neither templates nor files. For large template contexts, templateContentAccess points to the existing full-content read tool.

Compare several test cases together

begin_template_edit alternatively accepts testCases with one to five cases. Each case needs a unique caseId, a unique name and exactly one source: testDataId, testData or testDataArtifactId. Do not combine the list with the previous single-source arguments. All stored case data together must fit within 10 MiB. Selection, names and data remain immutable; context.testData still exposes the first case.

{
  "templateId": 123,
  "testCases": [
    { "caseId": "short", "name": "Short invoice", "testData": { "items": [1] } },
    { "caseId": "long", "name": "Long invoice", "testDataId": 456 }
  ]
}

After editing, call compare_template_edit with editId, a finalized draftArtifactId and a new UUID requestId. Optional caseIds explicitly selects distinct cases from this edit; omitting it selects every case. Each selected case renders the original and draft with the same stored data, brand and fixed reference time. Recovery preserves the original reference time. Charts, QR codes, components and attachments use that context too. Existing single render_template_edit calls remain available.

Starting returns comparisonId and queued immediately. Poll get_template_comparison with editId and comparisonId for completedSteps, totalSteps, currentStep and all steps, including case, side (original/draft), stage, private PDF or specific error. get_template_preview_info and get_template_preview_page support these PDFs and the existing overlay feature after the entire comparison completes. While rendering holds the edit lock, page requests can return CONFLICT; wait for completion instead of starting another rendering request.

completed means every selected pair succeeded. partial means some results exist alongside errors; failed, interrupted and stale are not successful acceptance either. Changed or unavailable dependencies require a new comparison. Compact status responses include original/draft hashes, case hashes, fixedDate, payloadSha256 and a fingerprint of the resolved dependencies for each result. Full IDs, versions and file/configuration hashes remain available for current permission and source checks. In the subsequent proposal, read the complete records through get_pending_change_content under fields.comparison.steps[].dependencies, following the returned content access with nextOffset and sha256. This evidence describes inputs supplied to rendering; it does not prove that every variable appeared in the PDF. Revalidating a completed comparison does not generate new PDFs.

outputBudgetBytes reserves a total output budget before starting, defaulting to 32 MiB, with an explicit maximum of 64 MiB within the remaining shared quota. It shares the existing 64-MiB quota with temporary files and other comparisons. Individual PDFs remain limited to 10 MiB, with at most 20 previews per edit. Actual output replaces the reservation and unused capacity is released at completion. Incomplete outputs belong to the edit too and are removed when it closes. PDFs inherit the shorter source expiry and remain subject to current source permissions.

An identical requestId never repeats rendering. Reusing it with different inputs or another editing operation is rejected. Unknown external results, including component TXT rendering, are never retried automatically. A reservation expires after 15 minutes without confirmed progress; status checks and ordinary file management detect those interruptions. Inspect partial results before making a deliberate new attempt with a new UUID.

Successful rendering still requires visual review and never saves or activates a template automatically.

Transfer files in the browser

Choose Files on an active connection to open its protected file dialog. The same dialog is linked by fileTransferUrl in get_mcp_context and browserUrl in artifact responses. These links contain no access tokens. You need the same active browser session used to approve the connection and the mcp:files scope.

An active connection with the required scopes alone is not sufficient: after a new browser sign-in, the earlier connection may remain active but offer only Revoke. For file access, approve a new OAuth connection in the current browser session. This does not adopt earlier files; use explicit recovery for previous template work. Finish an ongoing review before switching connections.

Select a file up to 10 MiB and start the upload. Browser and server verify size and SHA-256, followed by the existing file-format validation. Cancel pauses transfer. To Resume, select the same file again; the app checks the acknowledged server offset. Previously received chunks are not appended twice. Changed files need a new upload. Release file removes only the temporary file.

get_artifact_status without artifactId lists the current connection's permitted files and quota. With an ID it returns specific progress including receivedBytes, chunkBytes and nextOffset; null means no more upload chunks are missing. Only ready: true confirms successful validation. This lets the assistant find a browser-uploaded draft without reading its binary content. Existing chunk tools remain available for programmatic clients. Do not ask the language model to manually reconstruct binary files as Base64.

Choose Download for a validated file. The app verifies size and SHA-256 before starting the regular browser download. An MCP file read does not verify the file actually downloaded by the browser.

Existing limits remain: 100 files and 64 MiB reserved per user/tenant, expiring after at most 23 hours or when the connection expires, whichever is earlier. Revocation and current object permissions are enforced on access. Another browser login cannot automatically adopt existing files. Transfers do not change an active template; testing and confirmed approval remain separate steps.

Resume open template work

list_open_template_work returns up to ten currently permitted edits with template names, named cases, files, pending proposals, active comparison references, status and expiry. An unavailable source does not hide other work. Within the same valid connection, continue using existing edit and file IDs. Incomplete uploads can only resume within that connection; recovery after a new login copies finalized inputs only.

After a new browser sign-in, first approve a new OAuth connection with mcp:read, mcp:files and mcp:data in that browser session. Then open Integration → MCP connections → Open work for that new connection. Explicitly select the earlier edit and the desired DOCX draft. Review recovery lists every required input, including JSON test data and source files. Only Copy these inputs now creates a new edit and file IDs. Cancelling creates no copies. If the response is lost, repeat the same confirmation to receive the same result without additional copies.

Recovery requires the same user and tenant, their active non-delegated browser, read/file/data consent and current template-editor permission. All source bytes, checksums, object and sub-client permissions and expiry limits are checked again. Changed templates or a different effective sub-client require a new edit. An active operation must first reach a stable state. Expired comparisons are treated as interrupted during preparation; jobs are never automatically restarted.

The original, selected draft and required input sources receive new IDs and keep identical bytes. Rendering and brand resolution keep their original reference time; the new edit records its actual creation time. Retention never exceeds the shortest original source deadline, including after repeated recoveries. Browser confirmation expires after at most five minutes. Originals and copies share the existing quota of 100 files and 64 MiB; at most ten edits may remain open.

PDF previews, comparison jobs, old proposals and approvals are not transferred. Create and review a new comparison, then create a new change proposal. Old connections and tokens are never reactivated.

Discard earlier temporary work

After signing in again, you may explicitly clean up your own earlier work without recovering it first. list_open_template_work exposes the cleanup action. close_template_edit discards an edit and its temporary files; release_artifact discards an owned file and, where applicable, its associated earlier edit. Incomplete uploads can also be removed. The current connection requires mcp:files and the same user and tenant. If source permissions are no longer available, the listing contains cleanup IDs only, without source content. Reading and editing remain bound to the original session.

Active operations must finish first; a conflict does not mean cleanup succeeded. Successful cleanup releases quota, is audited and never changes a saved template. Closing one edit does not inadvertently delete test files shared with another edit.

Session expiry and parallel token renewal

Expiry or revocation immediately prevents connection access. Existing proposals remain visible to their owner and tenant in the browser within the existing retention period. This neither reactivates the connection nor extends approval validity.

During parallel refresh, the same client reusing the immediately preceding refresh token within less than 60 seconds receives the already-issued token pair. The reported access-token lifetime decreases accordingly. Older tokens, other clients, expiry, revocation and changed permissions remain blocked. Replay protection applies from 60 seconds onward. Operators can set MCP_REFRESH_RETRY_GRACE_SECONDS between 0 and 60 seconds; 0 disables the exception.