Work with a live PowerPoint presentation through MCP

Deckary's live document tools let an external AI agent work with the presentation currently open in desktop PowerPoint. Access is opt-in: the Deckary task pane must be open, you must be signed in, and MCP sharing must be enabled. Changes are executed by the add-in inside the live Office document. The same five tools also serve Excel workbooks and Word documents; this page covers what is specific to PowerPoint.

Start a live session#

1. Install and open the Deckary add-in in desktop PowerPoint.
2. Sign in with the same Deckary account used during MCP authorization.
3. Open the presentation you want the agent to access.
4. Turn on MCP sharing in the Deckary task pane.
5. Ask the agent to call list_live_documents and select the returned session whose kind is powerpoint.

Only active, explicitly shared sessions appear. The server does not search your computer for PPTX files and cannot queue offline work for a closed presentation.

Read before writing#

read_live_document returns a versioned projection with opaque slide handles (sl_…), the selected slide, slide dimensions, the outline, and every available layout. Pass slide handles as targets to also receive their editable scenes and the exact plain text of their text shapes. Pass ly_<layoutId> to receive one layout's placeholder obligations in detail.

The agent should keep the latest values returned by a successful live call:

• sessionId identifies the current shared presentation session.
• connectionGeneration distinguishes a reconnected add-in session from an older connection.
• artifactVersion represents the observed presentation state and is supplied as expectedArtifactVersion on the next call.

These values are concurrency controls, not stable document IDs. The agent should use current handles and versions rather than inventing or caching them across disconnected sessions.

Inspect only when deeper object truth is needed#

Use inspect_live_objects with shape handles (sh_…) for exact rich-text runs, fill and line appearance, text-frame state, native table structure, or Deckary chart configuration. An ordinary wording edit usually needs only a targeted read, because the read already returns exact plain text.

Large native tables may report that a range is required. Request a cell window with A1 notation, for example sh_table!A1:D10, instead of the whole table.

Render exact Office pixels#

render_live_document uses PowerPoint's native renderer and accepts up to four slide handles. The default overview detail returns one PNG per slide. For one slide, visualDetail=atlas also returns an overlapping 3×2 close-up atlas with current shape and text locators.

Rendering is useful when the external agent needs to judge hierarchy, spacing, clipping, contrast, or the visual result of a change. The external agent makes that judgment; the MCP server does not invoke a model to review the image.

Create or patch one slide#

author_live_document accepts one Slide DSL program for exactly one slide. It starts with slide { and can create a slide with an exact available layout or patch current shapes on an existing slide. Supported authoring includes text and shape changes, native tables and charts, and targeted deletions where the contract permits them.

Before the first write, have the agent call describe_authoring_vocabulary with the topics live_documents, powerpoint_dsl, powerpoint_program_body and, for chart edits, chart_actions. Call it again when a validation issue reports an unknown key. The recommended order is read_live_document → describe_authoring_vocabulary → author_live_document.

The live MCP path does not expose protected slide replacement or nonempty source bindings. A create operation must satisfy the selected layout's editable placeholder obligations. A patch must use current slide and shape handles.

Immediately before mutation, the add-in captures fresh Office truth and compares it with expectedArtifactVersion:

• version_conflict means the presentation changed. No mutation occurred. Read the current presentation and prepare the edit again.
• applied: false means no mutation occurred. Its validationIssues explain how to repair the program before trying again.
• applied: true is terminal success. The result already contains the next current state and exact committed Office pixels.
• settlement_unknown is not safe to retry automatically. Reconnect if required, read current presentation truth, and determine whether the change was already applied.

Do not immediately list, read, or render after applied: true only to refresh state; the successful result is already current.

Know when the session ends#

A live presentation disappears when you turn off sharing, sign out, close the Deckary task pane, or lose the add-in connection. Only one command can be in flight for a live session. If a session reconnects, use the newly returned generation and version.

For authorization and data-flow details, read Security and data handling. For recovery steps, see Troubleshooting.

Idle performance and freshness#

Enabling sharing captures the presentation once to register the session. While connected and idle, Deckary maintains the relay heartbeat without periodically scanning or exporting the presentation. Reconnecting reuses the last observation. Discovery metadata is last observed; use read_live_document for current content. Reads reuse observations for at most five seconds and refresh on demand when needed. Authoring always performs a fresh pre-write capture and version check.

Sharing is opt-in for the current loaded Deckary pane. A newly loaded pane starts with MCP disabled, even when the same account enabled it previously. Closing or reloading the pane clears consent and disconnects the live session.