Skip to main content

​
What is MCP?

Model Context Protocol (MCP) is an open protocol that lets AI clients connect to external tools. Nogic exposes a small, focused tool surface over MCP so AI clients can render diagrams directly onto the visualizer canvas.

​
Architecture

Nogic ships an MCP server inside the extension: there’s no remote service to point at and no API key to manage. When the extension activates, the server boots on an ephemeral 127.0.0.1 port and serves Streamable HTTP MCP at /mcp. When you press Cmd+K, the extension spawns the active CLI as a subprocess with this URL pre-wired. The CLI calls render / patch tools; the MCP server routes each call to the visualizer panel; the canvas updates in place. Third-party MCP clients (Cursor, Windsurf, etc.) aren’t supported yet — the bearer token + ephemeral port rotate every restart and Nogic can’t auto-rewrite their configs. Use Claude Code or Codex via Cmd+K for now.
The MCP port is ephemeral: it changes each time the extension activates. The MCP Setup overlay always shows the live URL, and Codex’s config is auto-rewritten on every activation. For external Claude Code and Cursor configs, you’ll need to update the URL when it changes, or use the Cmd+K flow which manages this for you.

​
Tool surface

The MCP server is intentionally narrow. It does not compete with the AI client’s native Read / Glob / Grep tools, which are faster than an HTTP roundtrip and tighter into the CLI’s permission model. Nogic owns canvas mutation only.

​
Generic tree canvas

​
render

Replace the canvas with a tree-structured spec. Use for the initial visualization or whenever the layout should change wholesale.

​
patch

Apply incremental changes (add/remove/move nodes, set props, set status, modify connections). Prefer over render once a base spec is on screen.

​
set_narrative

Install a step-by-step walkthrough. Each step focuses primitives, optionally reveals/hides nodes, sets the camera, and narrates.

​
focus

Drive the on-canvas cursor to a primitive by id without reflowing the canvas.

​
Dataflow

​
render_dataflow

Render a code-flow / pipeline / sequence diagram in the dedicated dataflow style: clean Dagre TB layout, simple shape nodes (cylinder for stores, box for services, circle for entry/exit), per-step active-pair box. Best for sequential pipelines and fan-out / convergence patterns.

​
patch_dataflow

Incrementally extend an active dataflow canvas: add new nodes (children, callees, sub-steps), wire them with edges, append narrative steps. Used for follow-up drill-ins.

​
Sequence

​
render_sequence

Render a UML-style sequence diagram: lifelines (service / database / external) with activity boxes and message arrows. Best for “what is the request/response order?”, “show me the protocol” questions.

​
patch_sequence

Add new activities and messages to an existing sequence.

​
State machine

​
render_state_machine

Render a UML-style state machine: states (with initial / final / error kinds) connected by transitions labeled trigger [guard] / action. Best for “what states does X go through?”, “show me the lifecycle / error handling” questions.

​
patch_state_machine

Add new states and transitions to an existing state machine.

​
ER diagram

​
render_er_diagram

Render a database / data-model ER diagram: tables with PK/FK badges and FK relationships wired field-to-field. Best for “show me the schema” questions.

​
Code tour (high verbosity)

​
render_code_tour

Walk the cursor through a curated subset of real code-graph nodes (files / symbols) step-by-step with per-step rationale. Each step targets a path-anchored ref the host resolves against the workspace symbol index (src/foo.ts, src/foo.ts:bar, src/foo.ts:42). Use when verbosity is set to high.

​
Configuring AI clients

Supported clients:

Claude Code

Per-call --mcp-config managed by the extension

Codex

Auto-managed ~/.codex/config.toml block