MCP server

noggin ships a Model Context Protocol server (noggin-mcp) that exposes the same verbs the VS Code extension's language-model tools do. Hosts that can't see in-process LM tools — GitHub Copilot CLI, Claude Code, OpenAI Codex — spawn this stdio server to get a complete noggin toolset for the agent.

What it is

A single Node 20+ binary, noggin-mcp, that:

Speaks MCP over stdio (one request per line of JSON, MCP framing).
Routes every tool call to the noggin named in the call's required noggin parameter (a canonical location string like ~/.noggin.yaml, ./.noggin.yaml, or file:///abs/path.yaml). One server can drive multiple noggins in a single session; there is no server-wide default.
Embeds the same @noggin/engine the CLI, VS Code extension, and desktop app use, so it shares the file watcher, the per-process verb queue, and the cross-process advisory file lock.
Wraps every result in the canonical response envelope — the same shape the CLI emits under --json and the same shape the VS Code LM tools return.

It ships three ways:

As a dedicated npm package, noggin-mcp, that exposes a single bin of the same name. The usual npx -y noggin-mcp@latest idiom just works.
Bundled inside the agent plugin (plugin/skills/noggin/noggin-mcp.bundle.mjs) for hosts that load plugins without running npm install (OpenAI Codex).
Bundled inside the VS Code extension (extension/skills/noggin/noggin-mcp.bundle.mjs), where the extension itself prefers in-process LM tools but the bundled server is available for external clients in the same workspace.

Choosing the right surface

Host	Use
VS Code (with the noggin extension)	In-process language-model tools — no MCP needed.
GitHub Copilot CLI (`copilot`)	MCP server, configured under `mcpServers`.
Claude Code	MCP server, configured in the host's MCP config.
OpenAI Codex CLI / app	MCP server, auto-launched by the agent plugin.
VS Code without the noggin extension	MCP server, declared in `.vscode/mcp.json`.

Wire it up

Most hosts share the same mcpServers shape. The recommended form pulls the latest release straight from npm — no clone, no install:

{
  "mcpServers": {
    "noggin": {
      "command": "npx",
      "args": ["-y", "noggin-mcp@latest"]
    }
  }
}

The noggin-mcp npm package ships a single bin of the same name, so npx -y noggin-mcp@latest resolves to the right executable with no extra hints.

File locations vary by host:

GitHub Copilot CLI — ~/.copilot/mcp-config.json (or your platform's equivalent under $XDG_CONFIG_HOME).
Claude Code — ~/.config/claude/claude_desktop_config.json on macOS/Linux, %APPDATA%\Claude\claude_desktop_config.json on Windows.
OpenAI Codex CLI — an [mcp_servers.noggin] block in ~/.codex/config.toml. The noggin plugin wires this for you when installed through the marketplace.
VS Code (without the noggin extension) — .vscode/mcp.json in the workspace, with the servers top-level key.

Local install (no npm)

If you've cloned this repo to hack on it, point the host at the file directly:

{
  "mcpServers": {
    "noggin": {
      "command": "node",
      "args": ["/absolute/path/to/noggin/mcp/noggin-mcp.mjs"]
    }
  }
}

Run npm install once inside mcp/ first, to pull in the MCP SDK and the workspace-linked @noggin/engine.

Tools

The server exposes 13 tools. Each one mirrors a CLI verb and returns the same response envelope; the agent sees a single canonical JSON shape regardless of which tool it calls.

noggin_show

Show the current-position view (spine + peers + first-level children). Default target is active.

Field	Type	Description
`noggin` required	`string`	canonical location of the noggin to operate on — e.g. `~/.noggin.yaml`, `./.noggin.yaml`, `/abs/path.yaml`, or `file:///abs/path.yaml`. Required on every tool call.
`path`	`string`	noggin path (absolute /1/2 or relative — see SKILL.md)
`noChildren`	`boolean`	omit first-level children of the target
`withSiblings`	`boolean`	also include ancestor sibling rows at every depth
`withDescendants`	`boolean`	expand the target subtree recursively
`withAll`	`boolean`	shorthand for withSiblings + withDescendants
`withNotes`	`boolean`	include note bodies after the tree (human-readable)

noggin_push

Create a child of active and immediately become it (going on a side-quest).

Field	Type	Description
`noggin` required	`string`	canonical location of the noggin to operate on — e.g. `~/.noggin.yaml`, `./.noggin.yaml`, `/abs/path.yaml`, or `file:///abs/path.yaml`. Required on every tool call.
`title` required	`string`	item title (one line)

noggin_add

Add a child without making it active (capture a deferred todo).

Field	Type	Description
`noggin` required	`string`	canonical location of the noggin to operate on — e.g. `~/.noggin.yaml`, `./.noggin.yaml`, `/abs/path.yaml`, or `file:///abs/path.yaml`. Required on every tool call.
`title` required	`string`	item title (one line)
`before`	`string`	place as sibling before this anchor path
`after`	`string`	place as sibling after this anchor path
`into`	`string`	place as last child of this anchor path
`goto`	`string \| boolean`	true = goto the target; string = goto this path after the verb

noggin_goto

Make the item at the given path active.

Field	Type	Description
`noggin` required	`string`	canonical location of the noggin to operate on — e.g. `~/.noggin.yaml`, `./.noggin.yaml`, `/abs/path.yaml`, or `file:///abs/path.yaml`. Required on every tool call.
`path` required	`string`	noggin path (absolute /1/2 or relative — see SKILL.md)

noggin_done

Mark target done and surface to its parent. Idempotent.

Field	Type	Description
`noggin` required	`string`	canonical location of the noggin to operate on — e.g. `~/.noggin.yaml`, `./.noggin.yaml`, `/abs/path.yaml`, or `file:///abs/path.yaml`. Required on every tool call.
`path`	`string`	noggin path (absolute /1/2 or relative — see SKILL.md)
`force`	`boolean`	close even if open descendants exist (leaves them open)
`closeAll`	`boolean`	cascade-close all open descendants first

noggin_pop

Shorthand for done on the active item.

Field	Type	Description
`noggin` required	`string`	canonical location of the noggin to operate on — e.g. `~/.noggin.yaml`, `./.noggin.yaml`, `/abs/path.yaml`, or `file:///abs/path.yaml`. Required on every tool call.
`force`	`boolean`	close even if open descendants exist (leaves them open)
`closeAll`	`boolean`	cascade-close all open descendants first

noggin_edit

Idempotent mutation of an item's state and/or title. Pass at least one of state or title.

Field	Type	Description
`noggin` required	`string`	canonical location of the noggin to operate on — e.g. `~/.noggin.yaml`, `./.noggin.yaml`, `/abs/path.yaml`, or `file:///abs/path.yaml`. Required on every tool call.
`path`	`string`	noggin path (absolute /1/2 or relative — see SKILL.md)
`state`	`string`	set done/open state (one of: `done`, `open`)
`title`	`string`	new title (rename)
`force`	`boolean`	close even if open descendants exist (leaves them open)
`closeAll`	`boolean`	cascade-close all open descendants first
`goto`	`string \| boolean`	true = goto the target; string = goto this path after the verb

noggin_note

Append a timestamped note to an item (default: active).

Field	Type	Description
`noggin` required	`string`	canonical location of the noggin to operate on — e.g. `~/.noggin.yaml`, `./.noggin.yaml`, `/abs/path.yaml`, or `file:///abs/path.yaml`. Required on every tool call.
`path`	`string`	noggin path (absolute /1/2 or relative — see SKILL.md)
`text` required	`string`	note body (free-form)

noggin_move

Relocate an item. Exactly one of before/after/into is required.

Field	Type	Description
`noggin` required	`string`	canonical location of the noggin to operate on — e.g. `~/.noggin.yaml`, `./.noggin.yaml`, `/abs/path.yaml`, or `file:///abs/path.yaml`. Required on every tool call.
`path`	`string`	noggin path (absolute /1/2 or relative — see SKILL.md)
`before`	`string`	place as sibling before this anchor path
`after`	`string`	place as sibling after this anchor path
`into`	`string`	place as last child of this anchor path

noggin_delete

Remove an item. Pass recursive=true if it has descendants.

Field	Type	Description
`noggin` required	`string`	canonical location of the noggin to operate on — e.g. `~/.noggin.yaml`, `./.noggin.yaml`, `/abs/path.yaml`, or `file:///abs/path.yaml`. Required on every tool call.
`path` required	`string`	noggin path (absolute /1/2 or relative — see SKILL.md)
`recursive`	`boolean`	also delete descendants

noggin_where

Return the canonical location string of the given noggin (echoes back the `noggin` parameter, useful for confirming the value the server interpreted).

Field	Type	Description
`noggin` required	`string`	canonical location of the noggin to operate on — e.g. `~/.noggin.yaml`, `./.noggin.yaml`, `/abs/path.yaml`, or `file:///abs/path.yaml`. Required on every tool call.

noggin_copy

Append every item from `from` into `to` (whole-noggin, append-only). New keys are generated; notes, done state, and createdAt timestamps are preserved verbatim. Use to migrate a noggin between locations or duplicate a tree under one root.

Field	Type	Description
`from` required	`string`	canonical location of the SOURCE noggin (read-only)
`to` required	`string`	canonical location of the DESTINATION noggin (mutated)

noggin_providers

List providers registered in this MCP server (e.g. file://). Useful for discovering what location forms the server accepts.

No parameters.

Response shape

Every tool returns the canonical response envelope as the text content of its MCP result. On success:

{
  "status": "ok",
  "envelopeVersion": 3,
  "verb": "push",
  "data": { /* CurrentTreeView, DeleteResult, ... */ }
}

On failure the MCP result is marked isError: true and the text content carries an error envelope with a stable error.code.

CLI reference — same verbs, different surface.
Response envelope — the JSON wrapper every tool returns.
JavaScript API — the in-process engine the server uses.
Skill spec — what the agent reads to decide when to call these tools.