MCP Overview

Documentation Index

Fetch the complete documentation index at: https://docs.nogic.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

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.

​

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: