MCP setup and tools — Proximaforma docs

Let your agent read and edit real design elements. The app supports local stdio and Streamable HTTP connections.

Connect an MCP client

Keep the Proximaforma app running.
Open Connect agent in the workspace.
Choose Copy setup instructions and paste them into your agent. Optional Access settings controls scope and expiry.
The agent chooses its own name and registers. It reads your canvas and comments, then confirms it is ready for instructions.

Registration gives the agent its credential and a Streamable HTTP configuration. It can use REST immediately, or add the MCP server if its client supports that. Otherwise, add the returned configuration in your client’s settings. For ChatGPT, use the account-linking flow below.

Setup links are private, valid for 24 hours, and work once. Fetching the guide does not use the link. If registration succeeds but its response is lost, revoke that connection and create a new link. Local setup links work only for agents on this computer.

Connect ChatGPT

Add to ChatGPT for guided desktop and browser setup, connection status, and mobile availability.

In the desktop connection form, choose Streamable HTTP and enter https://proximaforma.com/mcp. Save, then sign in. No command, client secret, or manual callback configuration is needed.

Revoke access from that canvas’s Connect agent panel. This also revokes token refresh. Account recovery revokes all existing connections. Linking does not allow creating other canvases or managing sharing.

Public directory installation requires OpenAI review and publication; it is not available merely because the server supports OAuth. Availability in ChatGPT, including on phones, depends on your account and workspace. See OpenAI’s connection guide.

Connect over Streamable HTTP

The setup guide tells the agent how to exchange its one-time link and chosen name for a scoped key. Registration returns the complete MCP configuration. For manual client configuration, use the values below. The endpoint uses stateless JSON responses.

Default HTTP connection values

Endpoint: http://127.0.0.1:4310/mcp
Transport: Streamable HTTP
Authorization: Bearer YOUR_API_KEY

If you changed the server port, use the endpoint shown in the app. The default server listens only on this computer; remote clients cannot reach it without a separate hosting and authentication setup.

Available tools

Tool	Purpose
`list_assets`	List saved image/SVG metadata, usage element IDs and the current revision.
`get_asset`	Read one image/SVG source before editing it.
`edit_asset`	Save or replace a reusable image/SVG, or delete an unused asset.
`list_comments`	Read feedback and replies, filtered by page or status.
`add_comment`	Pin feedback to a page or canvas location.
`reply_to_comment`	Reply to a colleague or agent in the same thread.
`update_comment_status`	Mark feedback new, in_progress, or handled with its comment revision.
`create_vector_path`	Create a custom path with anchors and optional cubic Bézier handles.
`create_vector_shape`	Create an editable line, triangle, polygon, or star.
`move_vector_point`	Move one zero-based path anchor and its handles.
`set_vector_point_handles`	Set or remove one anchor’s Bézier handles.
`smooth_vector_point`	Compute smooth handles for one anchor.
`corner_vector_point`	Remove one anchor’s handles to create a corner.
`split_vector_segment`	Insert an anchor while preserving the curve.
`delete_vector_point`	Delete one anchor and reconnect its neighbors.
`list_projects`	List projects and their current revisions.
`get_project`	Read a project’s complete element tree and activity. Pass optional elementIds to inspect specific elements and show their names in the agent activity panel.
`create_project`	Create an owned blank canvas or sample design. The connection can read and edit canvases it creates.
`create_invitation`	Create a single-use viewer or commenter invitation link, valid for seven days. No email is sent.
`add_element`	Add an element, optionally inside a frame.
`update_element`	Change an element’s position, appearance, text, or parent.
`delete_element`	Delete an element and its descendants.
`batch_edit`	Apply up to 200 operations as one atomic batch.
`reorder_element`	Change an element’s index in the flat element array.
`rename_project`	Give a project a new name.
`export_svg`	Export the current design as SVG.

Upload images and reuse SVG code

Call list_assets with projectId to discover uploaded images without loading their source data. Use get_asset with projectId and assetId to read an existing SVG before editing it. Both return the current revision and the IDs of elements using each asset.

MCP · save a reusable SVG

{
  "name": "edit_asset",
  "arguments": {
    "projectId": "PROJECT_ID",
    "revision": 0,
    "edit": {
      "op": "put",
      "asset": {
        "id": "brand-mark",
        "name": "Brand mark",
        "mimeType": "image/svg+xml",
        "width": 24,
        "height": 24,
        "data": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><circle cx=\"12\" cy=\"12\" r=\"10\" fill=\"#293324\"/></svg>"
      }
    }
  }
}

Then call add_element or batch_edit with the returned revision and an image element using assetId: "brand-mark" and imageFit: "contain". To upload a raster file, read and base64-encode its bytes locally and send a matching data URL in data. Local file paths and multipart uploads are not accepted by these JSON tools.

See the image asset API guide for formats, limits, replacement and deletion rules. Both HTTP and stdio expose the same tools.

Resources and editing guidance

The server exposes proximaforma://guide and proximaforma://projects/{projectId}. Connected agents also receive design instructions from the server.

Read the project before editing and pass its latest revision.
Use batch_edit with explicit element IDs to add frames and children together.
Keep parent IDs valid. Only frames can contain other elements.
Inspect the result after a change and refine as needed.

Manage agent access

Each named key is restricted to its owner’s accessible canvases, optionally one initial canvas, and to read, comment, or design access. Editing agents can create canvases and invite viewers or commenters. A canvas-scoped connection can access its initial canvas and canvases it creates; unrelated canvases stay private. Keys expire in 7–90 days and can be revoked. Agents cannot administer connections or remove members.

The stdio bridge uses the local workspace credential by default. For a named agent identity, set PROXIMAFORMA_API_KEY in its environment. Read Your data before connecting a provider.

Keep exploringGetting started Canvas guide REST API

Connect an MCP client#

Connect ChatGPT#

Connect over Streamable HTTP#

Available tools#

Upload images and reuse SVG code#

Resources and editing guidance#