PixAtlas MCP agents

For end-user setup in Claude, Claude Code and other assistants (in German, with an English summary), see PixAtlas für Claude und andere KI-Assistenten.

PixAtlas MCP gives an agent a selected set of resource workflows under your existing permissions. The integration uses stateless MCP 2026-07-28: every request supplies its identity and explicit organization/resource IDs. Availability depends on deployment configuration and acceptance checks; source implementation does not mean it is enabled in your environment.

Organization access

MCP requires an eligible Pro or Unlimited organization, current authenticated access and the organization's McpUse permission. Active members and users with supported authenticated resource shares can be eligible. Existing resource permissions still apply. A public share URL alone does not establish eligible access, and a license in one organization does not enable another.

Connect an agent

When available in your environment:

1. Open KI-Verbindungen in PixAtlas settings, choose Prompt kopieren and send the prompt to your agent. It contains the connection address and asks the agent to preserve its existing settings.
2. The agent configures the remote MCP connection and starts OAuth. Compatible public clients register their callback URLs automatically; users do not need to enter a client ID. The client must support MCP 2026-07-28.
3. Sign in through PixAtlas, including required MFA.
4. Review the client and select eligible organizations. Read-only is the default; select read and write only when needed.
5. Choose Interactive or Unattended operation. Unattended connections cannot perform actions requiring your confirmation.
6. Complete the connection in the client. When its runtime hostname is available, the setup prompt asks the agent to initialize the connection name as Agent · hostname. You can rename it in settings; automatic setup preserves an existing custom name.

Use the information icons beside the choices for details. They open on hover, keyboard focus or tap.

Scopes are pixatlas.read, pixatlas.write and optional offline_access. Consent limits access and never grants permissions you lack. Increasing access or changing organizations requires fresh consent; refresh can only preserve or narrow the original scope.

The server publishes discovery metadata at /.well-known/oauth-protected-resource/mcp/pixatlas. OAuth uses PKCE S256 and exact resource binding. OAuth discovery advertises an RFC 7591 registration endpoint for public clients using authorization code flow and PKCE S256. Registration identifies the application; it grants no organization or data access. HTTPS and numeric-loopback HTTP callback URLs are validated and registered without wildcards. Client-provided names are not proof of publisher identity. MCP credentials apply only to the MCP endpoint; use the existing browser or REST authentication flows elsewhere.

Client developers can also use metadata documents from an explicitly trusted publisher. The document must support the none token authentication method, either in token_endpoint_auth_methods_supported or, for older documents, token_endpoint_auth_method. A supported-method list takes precedence over the older preference. A client advertising several methods still uses PixAtlas's public-client flow with PKCE; JWT assertions and client secrets are not enabled.

Connect from ChatGPT

When your ChatGPT account and workspace allow custom MCP connections, open Plugins, select Add custom MCP server, and use the connection address from PixAtlas KI-Verbindungen. Choose OAuth, sign in to PixAtlas, and review the organizations and access on the consent page. Never paste a password, API token or personal access token into the conversation or server address.

Install the resulting personal plugin and select it in a new ChatGPT Work chat. Start by asking which connected organizations are available, then find a location or document. Keep read-only access unless your task needs changes. Destructive operations must still show a PixAtlas confirmation; if the client cannot complete that flow, the operation remains unavailable.

Custom connection availability and MCP protocol support depend on the client and workspace. A personal connection does not establish public Directory approval. If a public PixAtlas listing is available, install it through the Directory and use its normal OAuth flow. The integration accesses features already available to your account; it does not sell subscriptions or change billing.

See OpenAI's connection and testing guide for current ChatGPT steps.

Name this connection

initialize_connection_name accepts the agent runtime's short hostname and initializes only the current connection's unset name. It also works with read-only consent and changes no project data or permissions. Hostnames are display information, not verified device identity. If the agent cannot determine its hostname, it should skip this step; the registered agent name remains available.

Resource workflows

Start with get_connection_context and list_organizations. Use exact IDs from responses because names may be duplicated. Each call checks the selected organization's actual resource ownership and your current permissions.

Write commands use a stable idempotency key and original revision where required. After response loss, reuse the same key with identical arguments. A queued operation is not a completed result: check its status before continuing. Destructive actions require your confirmation. Agents that support MCP form elicitation (for example Claude Code) show a confirmation dialog. Other agents (for example Claude on the web, desktop or mobile) first receive a preview with status confirmation_required and nothing changes; the action runs only when the agent repeats the identical request with the single-use confirmationToken from that preview, which expires after ten minutes. Unattended connections cannot confirm. Existing pipeline job commands select configured versions; they do not accept arbitrary commands or create new pipelines.

File assignment means moving a file into an authorized document destination. It does not assign a document or task to a person. Document comments are read-only. Web-app reports and contact books are read-only and only available when the matching optional area was selected at consent; e-mail addresses, phone numbers, postal addresses and contact notes additionally require the personal contact details opt-in. The agent surface does not include person assignments, whiteboard tools, sharing, permission management, billing, personal account controls, notification consumption, camera writes or camera ZIP generation.

Document editing

Plain-text commands operate on bounded text with exact revisions. Reading never initializes collaboration state. Saving a checkpoint and publishing it as a file version are distinct operations. GAEB commands preserve supported XML structures and reject unsupported formats; they do not promise complete conversion support. PDF commands create a new version using a configured isolated processor. Unsupported processor isolation fails closed.

Original versions remain available. Publication preview and publishing support both inline text/GAEB checkpoints and existing app/web checkpoints in object storage, up to 8 MiB for plain text and GAEB. The server verifies the encoded size and SHA256 before preview and again during publication. Preview creates no checkpoint or file version. A queued edit/publication must be checked for completion. PDF content covers are not certified secure redaction. General DOCX, XLSX and PPTX editing is not offered by these specialized tools.

Read document text and organize files

Use read_document_text for an authorized PDF. It works on read-only connections and never starts extraction: it returns completed OCR text, or otherwise the PDF's embedded text layer that is already stored for search (textSource tells you which). Scanned pages without a text layer only become readable after OCR. To run OCR, use prepare_document_text with the returned source version, then read the same document again for status and paged text. Preparation requires write consent, so on a read-only connection ask a user with write access to prepare the text. The PDF stays unchanged. Failed extraction requires an explicit retry. Non-PDF files return unavailable.

delete_library_folder removes an empty ordinary folder after your confirmation. Use its current path and revision from the folder list. A managed folder, child folder or retained document version prevents deletion.

To restore a stored file version, use preview_document_version_restore, then restore_document_version with the exact source/head revisions. Restoration queues a new version and preserves the originals. Poll get_document_publication until it completes before using the returned file ID. Both the selected version and current head require Write access, and the new copy consumes document storage. Restoration supports retained uploads with a recorded SHA256 checksum, up to 5 GiB and 100 versions in the lineage.

Assign a document to a Project

Assignment moves the entire version history. Use preview_document_assignment with the newest document ID, source library, destination Project library and folder. Then use assign_document with the preview fingerprint, current document revision and a stable retry key, and confirm the move in your agent. All versions keep their IDs and stored files; no second storage copy is charged. Your connection needs write consent and Write access to every historical source path and the destination.

The libraries must belong to the same organization, with at least one Project involved. Up to 100 versions move together; larger histories are rejected without a partial move. Linked reports, collaborative drafts, annotations, external shares or unfinished replacement work can prevent moving a history. The tool returns a conflict instead of breaking those relationships. After a lost response, reuse exactly the same arguments and key to recover the committed result.

Upload and render a model

Use list_model_render_presets to discover available Turbo, Standard and Detailed processing. Provide the model name, capture date and photo/video file metadata to start_model_capture_upload. Turbo and Standard accept photos; Detailed also accepts video. Optional supported GPS sidecars stay associated with the capture. At least three photos or one supported video are required.

Your agent's file-transfer integration uploads the bytes, checks completion and finalizes the input bundle using the transfer handles. A capture can contain up to 500 files within the request-size limit; files are never silently dropped. Call render_model_capture with the completed bundle and selected preset, review the confirmation, then track get_model_render_status. Rendering does not require choosing internal pipeline IDs. Reuse the original key after a lost admission response to avoid submitting another job.

Cameras

Camera access remains read-only even when you grant write consent. You can inspect camera metadata, list or seek retained captures and view bounded timeline information. Use download_camera_capture with the exact camera, capture and historical location IDs to get a temporary download URL. Treat the URL as sensitive; an issued URL can remain usable until its expiry. Agents cannot pair devices, change camera settings, delete captures or generate capture ZIP files.

Chat and attachments

Start with list_chat_rooms and get_chat_history. Reads use your existing Matrix identity without exposing a Matrix token or session. They never provision or join rooms. Original Matrix sender fields are retained; copied prefixes or remote claims do not establish verified agent authorship.

get_chat_message reads your own plaintext message and its bounded replacement snapshot. get_chat_pins returns visible preferences without changing hidden entries. find_chat_messages searches one authorized room with a bounded page and a ten-minute cursor tied to the delegation, room, query and page size.

get_chat_attachment_metadata identifies an exact authorized message attachment without exposing its MXC URI or credentials. read_chat_attachment_chunk requires its snapshot revision and returns bounded base64 chunks: default 32 KiB, maximum 64 KiB per call, with a 32 MiB observed total-size limit. Access is rechecked during streaming. Unsupported range reads fail explicitly.

Encrypted rooms and attachments return encryption_requires_supported_device. Chat reads do not send or edit messages, redact content, react, change pins, acknowledge messages or upload attachments.

GAEB and bills of quantities

Agents can inspect an uploaded GAEB bill of quantities, offer, order or invoice with inspect_gaeb_document. One response contains the detected XML edition and exchange phase, hierarchy, totals, first positions and validation findings. It works with read-only access and does not require an editing session or a separately installed skill.

query_gaeb_positions filters positions by ordinal prefix, text or unit. validate_gaeb_document pages through findings, and compare_gaeb_documents compares two documents by unique ordinal number. Replies include the document revision and further-page information. Ambiguous duplicate ordinals are reported rather than matched arbitrarily.

get_gaeb_guidance provides the embedded GAEB workflow and references on formats, hierarchy, totals, split rules and invoice questions. Clients supporting Skills-over-MCP can discover the same knowledge automatically; ordinary MCP clients can retrieve it through this tool. Inspection replies also contain the relevant coverage guidance.

Native reads support GAEB DA XML 3.1–3.3 up to 64 MiB. Validation covers structure, numeric fields and simple position calculations. Complex financial rules are marked as partially covered, and official schema and cryptographic signature checks remain unverified. Split/recalculation and legacy D/P formats are not native MCP operations in this release. Editing supports checkpoints up to 8 MiB and 250000 XML elements while preserving untouched content and the original encoding.

Edit the shared GAEB document live

Use get_gaeb_document for the current working state. Its textFilter, ozPrefix and kind filters narrow the positions returned; includeLongText includes descriptions when needed. Text search covers complete descriptions even when the returned text projection is shortened to 4,000 characters. Paragraph and line-break boundaries are retained in the projection. The result identifies the collaboration, current revision and published file head. Reading uploaded bytes with query_gaeb_positions does not include unpublished edits.

Apply changes with apply_gaeb_commands using those paths and baseRevision. A batch accepts 1–32 commands and one idempotency key. Command IDs are optional; the server assigns stable identities. SetField changes quantities, unit prices and descriptions; missing UP/IT values can be inserted in supported GAEB item order. Nested short/long descriptions can be changed without deleting their wrappers. For several text runs, matchText replaces a unique existing substring and preserves surrounding formatting, including matches inside long existing text leaves. DuplicateNode accepts value as the copied item's or section's new RNoPart; duplication, movement and ordinal edits reject destination collisions with the same ordinal index.

The backend commits the same checkpoint used by the human editor and queues a SignalR revision notification. An already-open authorized editor on that collaboration receives the revision and resynchronizes. The MCP receipt proves the saved revision; it does not prove that a particular browser displayed it. A separately uploaded replacement has a separate working state, so normal live changes should use the existing collaboration.

If no working state exists, initialize the exact selected upload with initialize_gaeb_edit_state. Publish a downloadable file version with the existing publication tools, using the preview's metadataFingerprint as destinationRevision and its size as expectedSizeBytes. Both GAEB and plain-text publication accept checkpoints up to 8 MiB. An open app can publish a new head while an agent is preparing publication; an outdated preview is rejected and requires a fresh preview and reconciliation. A queued receipt is followed by get_document_publication to establish completion. Field changes do not automatically recalculate dependent totals; verify item and LV totals before publishing. get_gaeb_guidance with editing or tools explains this workflow and correctable errors for any MCP client.

Review connections

Use the AI connection settings in PixAtlas to review consent and revoke a connection you own. Open Access details to inspect the selected organizations, read/write access and expiration. The owner-only GET /v1/users/me/mcp-connections/{connectionId}/grants response exposes the consented scope list as oauthScopes. Revocation prevents further authorized agent work. Client compatibility and deployed availability must be checked in the environment you use.

PixAtlas opens connection approval on its dedicated authentication subdomain. You may be asked to sign in there even if the app is already open. This uses the same PixAtlas account and MFA; the connection still has only the access you approve. Use the current bridge release so it recognizes the separate approval page.

Live editing beyond quantities

GAEB X86 editing supports typed new positions and sections (InsertPosition, InsertSection), full short/long descriptions, section labels, and structural commands. The server creates the XML and identities. replaceTextStructure explicitly replaces a description's formatting with plain paragraphs; matchText preserves the existing formatting around a unique text match. Prices and totals remain explicit values.

Plain-text files support exact replacements through replace_document_text, including adding or deleting paragraphs. Paged working-state reads return nextOffset; expectedRevision keeps successive pages consistent. GAEB and plain-text checkpoints support up to 8 MiB, subject to bounded tool inputs and responses.

Committed changes notify connected editors through SignalR. Editing keeps the same collaborative document; publishing creates a downloadable version. Uploading a separate replacement creates a separate editing state.