MCP, REST, and the in-app Agent

Eidograph offers three paths for agents, all ending at the same tool surface:

Path	Best for	Available in
In-app Agent	Natural-language changes to the current project	Windows and Android apps
MCP Streamable HTTP	Agent platforms that support remote HTTP MCP	Windows app
JSON REST API	Scripts, workflows, and custom agents	Windows app

Before a tool changes a script, Eidograph compiles the candidate. An edit with compiler errors or a skipped-command warning is rejected and the current script is unchanged. Successful edits persist, redraw, and enter normal undo history immediately.

Enable the native server

1. In the installed app, open Settings › MCP / REST server.
2. Enable the server and confirm that its status is running. The default port is 14159.
3. Enable only the tools the client needs.
4. In Figures, inspect the exposure dot beside each figure. A filled dot means external clients may access it.
5. Keep the default loopback binding unless you are on a trusted network.

Default endpoints:

MCP   http://127.0.0.1:14159/mcp
REST  http://127.0.0.1:14159/api/v1

DANGER

LAN mode binds to 0.0.0.0 and has no internet relay. Native clients on that network can invoke the tools you enabled, so turn on an access token before you turn LAN mode on, use it only on a trusted network, and turn it off afterward.

Require an access token

The server is unauthenticated by default, which is safe enough while it stays on loopback: only programs already running on your PC can reach it. Turn on Settings › MCP / REST server › Require an access token — always before enabling LAN mode — and Eidograph generates a secret that every request must carry:

Authorization: Bearer <token>

Requests without it are answered 401. Settings shows the token with a copy button, Replace the token rotates it, and switching it off clears it. Both take effect at once, so update every client you have configured.

Find the server from another program

The port is a setting, so nothing outside the app can assume it. While the listener is up Eidograph publishes a discovery file, and deletes it when the server stops or the app quits:

Platform	Path
Windows	%LOCALAPPDATA%\eidograph.metaphor.projects\server.json
macOS	~/Library/Application Support/eidograph.metaphor.projects/server.json
Linux	$XDG_DATA_HOME/eidograph.metaphor.projects/server.json

{
  "version": "0.2.19",
  "pid": 24680,
  "updatedAt": 1757000000000,
  "bindAddress": "127.0.0.1",
  "port": 14159,
  "mcp": "http://127.0.0.1:14159/mcp",
  "api": "http://127.0.0.1:14159/api/v1",
  "token": "3f9c…",
  "lanAddresses": []
}

Read mcp or api, and send token as a bearer token; it is null when none is required. The published URLs stay on loopback even in LAN mode, because every reader of this file is on the same machine. Settings › MCP / REST server shows the exact path and copies it. Treat a missing file as "the server is not running" rather than falling back to a guessed port.

Claude Desktop

Claude Desktop installs MCP servers as local stdio processes, so an HTTP URL cannot be pasted into it directly. Install the eidograph-mcpb extension to bridge the two — it needs no configuration, finding the port and access token by itself and re-reading them on every request. See Claude Desktop for step-by-step installation with screenshots, and how to point it at Eidograph running on another device.

Connect an MCP platform

For a client that supports Streamable HTTP—including the Trae / WorkBuddy configuration copied by the app—add this server:

{
  "mcpServers": {
    "Eidograph": {
      "url": "http://127.0.0.1:14159/mcp",
      "transport": "streamable-http",
      "disabled": false
    }
  }
}

Platforms differ in configuration file location and outer schema, but the essential values are the server name, URL, and Streamable HTTP transport. If a platform supports only a local stdio MCP process, do not put this URL in its command field; use an HTTP connector or bridge supported by that platform.

After connecting, let the client discover tools, then read the current script or command registry. A reliable agent sequence is:

1. list_figures to confirm the target;
2. get_script and list_objects to understand the current figure;
3. list_commands to inspect valid syntax for the active 2D/3D dialect;
4. append_commands for additive changes, and set_script only when existing lines must be rewritten;
5. list_diagnostics to verify the result and correct any issue.

Call the REST API

For endpoint contracts, every tool schema, export encoding, error behavior, and JavaScript/Python/PowerShell examples, see the REST API Reference.

Check status and tool discovery first:

curl http://127.0.0.1:14159/api/v1/status
curl http://127.0.0.1:14159/api/v1/tools

Create two points and a segment:

curl -X POST http://127.0.0.1:14159/api/v1/tools/append_commands \
  -H "Content-Type: application/json" \
  -H "X-Eidograph-Client: my-agent" \
  -d '{"commands":"point A -2 0\npoint B 2 0\nsegment s A B"}'

Responses use one envelope: {"ok":true,"result":...} on success or {"ok":false,"error":...} on failure. The optional X-Eidograph-Client header gives the caller a readable name in Settings activity.

The current surface can read and list figures, create figures, append or replace scripts, list objects/diagnostics/commands, select an object on canvas, and export an exposed figure as SVG, PNG, GIF, or MP4. Tool permissions and figure exposure are enforced on every call.

Configure the in-app Agent

Save several models in Settings › Agent, then switch among them from the Agent header. Eidograph supports three protocol families:

• OpenAI-compatible Chat Completions endpoints;
• Anthropic Messages;
• Google Gemini / Vertex generateContent.

Each saved model has a display name, provider, Base URL, API key, and model ID. You can enter an ID manually if model discovery fails. Local endpoints such as Ollama and LM Studio can work as well, but the endpoint must allow cross-origin requests from the app's WebView (CORS).

The in-app Agent accepts attached or pasted images, which is useful for turning a textbook photo or sketch into a construction. Vision support is determined by the model endpoint; an unsupported request appears as an error in the conversation.

Permissions and data boundaries

• In-app and external agents have no hidden privileged path; both use the same tool definitions.
• External edits target the active project and honor each figure's exposure state.
• API keys are never written to .eido. The Windows and Android apps use protected OS credential storage.
• Agent chats are excluded from .eido by default and are shared only when Include agent chats is enabled explicitly.