Octonode MCP server — project authoring, plugins, workflows, and collaboration

@octonode/mcp is a Model Context Protocol server that lets any MCP client (Claude Code, Cursor, Windsurf, …) author Octonode plugins. It speaks MCP's stdio transport (newline-delimited JSON-RPC) with zero dependencies.

Tools

The server also exposes focused collaboration tools backed by the Hono API:

Agent-token creation and browser realtime ticket minting are intentionally not MCP tools: an owner creates credentials through the authenticated Studio/API, and realtime sockets remain a browser session capability. Every MCP mutation is checked again by the Cloud API; the MCP process carries no GitHub installation token or persistence logic.

Repository operations use architectureId; workflow review operations additionally require the contained projectId. There are no project-level GitHub connect or unlink tools.

Every write is validated against the manifest schema, so an agent cannot produce a structurally-broken plugin.

Project-authoring tools are API-backed and require OCTONODE_PROJECT. The project id is attached by the MCP process, never accepted as a model tool argument. Reads require projects:read, writes use projects:write, and runs/cancellation use workflows:run; the API checks the scoped credential on every call. The initial surface covers bounded project context/files/source, nodes, workflows, the native and installed-plugin catalogs, canonical Octonode knowledge, revision-safe topology/source writes, validation, run history, workflow runs, and cancellation. It intentionally has no shell, arbitrary path, delete, Git publish, marketplace publish, workspace administration, generic HTTP, or secret-read tool.

resources/list and resources/read expose the canonical octonode-code-author skill and a public documentation index. tools/list includes read/write annotations; the same neutral descriptors are consumed by the chat service.

Exercising workflows

The first six tools author plugins; the last two let an agent run what it built against the project's .octonode config (config → code routing happens inside the engine — these tools never touch source).

run_workflow

Executes a workflow and returns a compact summary.

Arguments:

Result on success:

{
  "ok": true,
  "status": "ok",           // "ok" | "partial" | "error"
  "runId": "…",
  "durationMs": 1234,
  "nodes": { "<nodeId>": { "status": "ok", "durationMs": 42 } },
  "outputs": { "<terminalNodeId>": { /* node outputs */ } }
}

On failure (config not found, unknown workflow, cycle, …) it returns { "ok": false, "error": { "message": "…" } }.

describe_node

Resolves a node's command from the config and asks the node process to self-report its manifest (declared inputs/outputs, icon, default config).

Arguments:

Result on success: { "ok": true, "nodeId": "…", "manifest": { /* manifest envelope */ } }. If the node reports an error (or fails to spawn) it returns { "ok": false, "nodeId": "…", "error": { /* NodeError */ } }, and any thrown error (config not found, node missing/orphaned, …) becomes { "ok": false, "error": { "message": "…" } }.

Running it

octonode mcp              # run on this process's stdio
# or the standalone binary:
octonode-mcp

Client configuration

Claude Code

claude mcp add octonode -- octonode mcp

or in .mcp.json (project-scoped):

{ "mcpServers": { "octonode": { "command": "octonode", "args": ["mcp"] } } }

Cursor (~/.cursor/mcp.json) / Windsurf / any MCP client:

{ "mcpServers": { "octonode": { "command": "octonode", "args": ["mcp"] } } }

If octonode isn't on PATH, use the absolute path to the CLI (or octonode-mcp).

For collaboration tools, configure the Hono API and one user or scoped-agent credential:

export OCTONODE_API_URL=http://127.0.0.1:8787
export OCTONODE_API_TOKEN=<supabase-jwt-or-octo_agent_token>
export OCTONODE_WORKSPACE=org:<workspace-id>
export OCTONODE_PROJECT=<authorized-project-id>
octonode mcp

The workspace is attached to every request. Mutations receive a fresh idempotency key, API errors preserve status/conflict details, and binary backup/avatar responses are returned as base64.

Claude Code skill

A companion skill lives at skills/octonode-plugin-author/SKILL.md — copy it into your project's .claude/skills/ (or ~/.claude/skills/) so Claude Code knows the manifest format, the IPC node contract, and when to reach for these tools. Other agents can read the same file as authoring guidance.

Protocol notes

• Transport: stdio, newline-delimited JSON-RPC 2.0 (one message per line).
• Implements initialize, tools/list, tools/call, ping, and the notifications/initialized notification. serverInfo.name is octonode-mcp.
• stdout carries only JSON-RPC; all logs go to stderr.