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.

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.

Alternatively, add an HTTP server under Settings > MCP servers in the Codex app and start authentication. 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 following extensions are released for production. Sign in to your connection again and explicitly approve the additional permissions you need. For example, to edit templates 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.”

The client edits the DOCX locally; Output.Rocks supplies files, context and previews over MCP 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.

Practically tested: Codex. Claude/Cowork and GitHub Copilot in VS Code have not been practically tested.

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. Select the exact template version and test data with list_entities. Resolve duplicate identifiers by brand and subclient before choosing a version ID.
2. Call begin_template_edit with templateId and testDataId. The session contains the original DOCX, its checksum, and an immutable context.
3. Read every chunk from get_template_edit_context for metadata, assignments, and test data. Use get_template_syntax for syntax guidance; the original file remains complete.
4. Call render_template_edit without draftArtifactId for the baseline PDF. Download the original, edit it in the client, and upload the draft with the file tools above.
5. Call the same tool with draftArtifactId to render the draft. Both versions use the existing Template Editor with identical stored test data and date. Download the complete PDF using read_artifact_chunk.
6. After visual inspection, call propose_template_update with editId, draftArtifactId and a concrete summary. Open the returned approval link to compare original and draft in the browser. Keep the editing session open until the decision is complete.
7. close_template_edit removes the session, original copy, rendered drafts, and preview PDFs. Release unused uploads separately with release_artifact.

Rendering neither saves nor activates the source template. Only browser approval saves the draft. Configuration changes cause a conflict; start a new session. Limits are ten sessions per user and twenty previews per session, plus the general file and expiry limits. Contexts larger than 2 MiB are explicitly rejected. Secrets are removed from test data too.

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. The existing 14 tools retain their behavior. Claude/Cowork and GitHub Copilot in VS Code have not been practically tested for this workflow.

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.

Practical client acceptance uses Codex; Claude/Cowork and GitHub Copilot in VS Code are not practically tested.

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. Claude/Cowork and GitHub Copilot in VS Code have not been practically tested; client acceptance uses Codex.

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.

Codex is used for practical acceptance. Claude/Cowork and GitHub Copilot in VS Code are not practically tested.

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.

Practical acceptance uses Codex; Claude/Cowork and GitHub Copilot in VS Code are not claimed as practically tested.

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. Practical client acceptance uses Codex; Claude/Cowork and GitHub Copilot in VS Code are not practically tested.

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.