MCP Tool Reference
The MCP server registers JSON-returning tools. Local stdio writes honor IDEAGRAM_MCP_READ_ONLY=true. Remote HTTP writes honor the authenticated token scope and user permissions. Tool calls emit structured audit logs without secrets or full diagram payloads.
The server does not inherit the diagram currently open in a browser tab. Discover resources and pass the IDs requested by each tool. Use the schemas returned by your MCP client's tool discovery for required fields and accepted values.
Workspace, Organization & Project Tools
Discovery tools return organization, workspace, and project IDs for subsequent calls. These are how a client with nothing but a token discovers one — or creates a brand new workspace, project, or diagram instead of only operating on ones that already exist.
| Tool | Access | Purpose |
|---|---|---|
list_organizations | read | List organizations the authenticated user belongs to, with their role. |
list_workspaces | read | List workspaces in an organization. |
list_projects | read | List projects in a workspace. |
create_workspace | write | Create a workspace in an organization. |
create_project | write | Create a project in a workspace. |
create_diagram | write | Create a new, empty diagram in a project. |
Diagram Tools
| Tool | Access | Purpose |
|---|---|---|
list_diagrams | read | List diagrams visible to the configured context. |
get_diagram | read | Return a diagram with components and connections. |
add_component | write | Add a component to a diagram. |
update_component | write | Patch component fields such as position, dimensions, and properties. |
add_connection | write | Add a connection between two existing components. |
update_connection | write | Patch connection label, style, type, handles, or control points. |
create_version | write | Create a version snapshot after MCP-driven edits. |
validate_diagram | read | Run Ideagram rule-based validation for a diagram. |
export_mermaid | read | Export the diagram as Mermaid text where supported. |
export_plantuml | read | Export the diagram as PlantUML (sequence, class, state, ER, flowchart, C4; the flowchart is a one-way approximation). Other families return plantuml: null, a reason, and the Mermaid text. |
apply_mermaid | write | Apply Mermaid text to the diagram. mode: "replace" (default) swaps the content; mode: "merge" edits it — components the text still names keep their id, position and Model link, new ones are placed beside them, dropped ones are removed (same kind of diagram only). The previous content is saved as a version first (snapshot: false to skip); dryRun: true previews what would change without writing. |
apply_plantuml | write | Replace the diagram's content with PlantUML (sequence, class, state, ER, C4). Same options as apply_mermaid. |
reclassify_diagrams | read / write | Report (default) or apply (dryRun: false) moving legacy uml/freeform diagrams to flowchart, class, sequence, state or ER when all their content belongs to that family. Mixed drafts and C4 stay, with the reason. |
Model Tools
| Tool | Access | Purpose |
|---|---|---|
list_model_entities | read | List project model entities, optionally filtered by type or name. |
get_model_entity | read | Fetch one model entity, optionally including linked diagram instances. |
upsert_model_entity | write | Create or update a project model entity. |
link_component_to_model_entity | write | Link a diagram component instance to a model entity. |
unlink_component_model_entity | write | Clear a component's model entity link. |
list_model_relationships | read | List project model relationships. |
get_model_relationship | read | Fetch one model relationship, optionally including linked diagram connections. |
upsert_model_relationship | write | Create or update a project model relationship. |
link_connection_to_model_relationship | write | Link a diagram connection instance to a model relationship. |
unlink_connection_model_relationship | write | Clear a connection's model relationship link. |
backfill_diagram_model_links | write | Create/link model records from an existing diagram. |
Documents, Notes & Folders (Pages)
MCP provides the document and folder operations below, including structured ADR/spec upserts. A folder or document may have organization, workspace, or project scope. Cross-links, questions, and pending proposals are project-scoped. The table does not imply parity with every UI action, such as trash recovery.
| Tool | Access | Purpose |
|---|---|---|
list_folders | read | List document folders for an organization, optionally scoped to a workspace or project. Returns a flat list and a nested tree. |
list_documents | read | List project documents and notes (summaries), optionally filtered by folder or kind. |
get_document | read | Return one document or note with its full content. |
get_project_context | read | Aggregate a project into one payload: folder tree, documents, diagrams (Mermaid when includeBodies), the semantic model, and cross-links. The entry point for an IDE agent pointed at an Ideagram project. |
create_folder | write | Create a document folder. |
create_document | write | Create a document or note (kind: document | note). |
update_document | write | Patch a document: title, content, status, kind, and/or folder. |
move_document | write | Move a document to a folder (or back to the scope root). |
upsert_decision | write | Create or update a decision record (ADR): status + context / decision / consequences. |
upsert_spec | write | Create or update a spec document: status + problem / goal / non-goals. |
list_links | read | List cross-links in a project, optionally filtered to one entity. |
link | write | Create a cross-link between two project entities (document/diagram/model entity). Idempotent. |
unlink | write | Delete a cross-link by id. |
Pending Changes & Questions
With a propose token, upsert_decision and upsert_spec queue changes for review. Other permitted writes apply directly; this scope is not universal approval gating. A write token is required to resolve a proposal. Agents can also ask a clarifying question and poll for its answer.
| Tool | Access | Purpose |
|---|---|---|
list_pending_changes | read | List queued decision/spec proposals for a project, optionally filtered by status. |
resolve_pending_change | write | Approve (apply) or reject a queued proposal. |
ask_question | write | Raise a clarifying question against a project (optionally targeting a document/diagram/spec/decision). |
list_questions | read | List the project questions, optionally filtered by status (open | answered | dismissed). An agent polls status=answered to resume. |
answer_question | write | Answer an open question. |
dismiss_question | write | Dismiss an open question without answering. |
Skills
| Tool | Access | Purpose |
|---|---|---|
list_skills | read | List the available skills (packaged prompt + tool subset). macro skills run server-side; assisted skills return a prompt + context for the calling agent. |
run_skill | varies | Run a skill by id with args (skill-specific). Gated by the calling token scope when the skill writes. |
Example Prompt
Use the Ideagram MCP server to list my diagrams, open the API architecture diagram, validate it, then explain any warnings.
Write Example Prompt
Use the Ideagram MCP server to list my projects and diagrams. Ask me to select the project and diagram, then create a model entity named AuthService and link the matching component in that selected diagram to it.
Full-Loop Example Prompt
Use the Ideagram MCP server to: list my organizations, create a new project called
"Payments Service" in my workspace, create a C4 container diagram for it with a web
app, an API, and a database, connect them, then create an ADR page in that project
documenting the decision to use Postgres.
This is the same discover → create → document loop the in-app editor uses, driven end to end from a CLI, Cursor, Claude Code, or any other MCP client — see Remote HTTP MCP for the hosted endpoint.