> ## 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.

# MCP Overview

> How Nogic's local MCP server lets AI clients drive the canvas

## What is MCP?

[Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#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.

<Warning>
  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.
</Warning>

## 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:

<CardGroup cols={2}>
  <Card title="Claude Code" icon="terminal" href="/mcp/claude-code">
    Per-call `--mcp-config` managed by the extension
  </Card>

  <Card title="Codex" icon="robot" href="/mcp/codex">
    Auto-managed `~/.codex/config.toml` block
  </Card>
</CardGroup>