MCP setup

Give an AI client scoped tools to inspect, edit, validate, and run Octonode workflows.

Octonode's Model Context Protocol (MCP) server exposes tools that an AI client can discover and call. The client supplies the model; Octonode supplies project tools. The standard project connection is the hosted Streamable HTTP endpoint at https://mcp.octonode.dev/mcp. Otto already has this connection built in.

Before you connect

You need an Octonode access token, a workspace ID, at least one project ID, and an MCP client that supports Streamable HTTP. Configure the client's model or provider account separately.

First verify your access token and API connection. A workspace or project header selects context but does not grant permission beyond that token.

Connect a project

The octonodes CLI from the Octonode devtools repository generates scoped configuration without copying a saved token into Codex config:

octonodes login
octonodes connect codex --workspace org:WORKSPACE_ID --project PROJECT_ID
octonodes connect claude --workspace org:WORKSPACE_ID --project PROJECT_ID

Copy the Codex command's output into ~/.codex/config.toml. It uses a local header helper backed by the saved login. The Claude command prints a claude mcp add-json command; export OCTONODE_TOKEN in Claude's environment before running it. Repeat --project for a multi-project allow-list and add --worktree WORKTREE_ID only when targeting a managed checkout.

Clients configured directly must send these HTTP headers:

Header	Value
`Authorization`	`Bearer YOUR_OCTONODE_TOKEN`
`x-octonode-workspace`	`user:ID`, `org:ID`, or `team:ID`
`x-octonode-project`	Default project ID
`x-octonode-projects`	JSON array of allowed project IDs
`x-octonode-worktree`	Optional managed checkout ID

Use your client's secret or environment configuration when available. Never commit a token or a generated authorization header. Restart or reconnect the MCP server after changing its scope.

Verify tools before making changes

Open the client's MCP tool list, then ask it to call project_context and project_workflows. You should see the files and workflows of the intended project. If either points to the wrong project, correct the configuration before allowing edits.

Task	Tools	Typical scope
Inspect source	`project_context`, `project_file_read`, `project_source_index`	`projects:read`
Inspect a workflow	`project_workflows`, `project_workflow_graph`	`projects:read`
Edit a file	`project_file_create`, `project_file_write`	`projects:write`
Add nodes and connections	`project_native_materialize`, `project_workflow_save`	`projects:write`
Compile after edits	`project_validate`	`projects:write`
Execute or cancel	`project_workflow_run`, `project_workflow_cancel`	`workflows:run`
Inspect execution history	`project_runs`, `project_run`	`projects:read`

File and graph writes use the revision returned by a preceding read. On a revision conflict, re-read and reconcile changes before retrying. A workflow run can invoke external services; enable execution only for an integration that needs it.

Give the assistant a precise first task

Use the Octonode MCP connection to inspect the selected project.
Call project_context and project_workflows, then read the relevant source.
Report the existing workflow IDs, inputs, outputs, and missing configuration.
Do not edit files or run workflows during this inspection.
Never include credentials in your response.

For a build task and reusable project instructions, continue with AI assistants and skills.

Local plugin authoring

octonode mcp remains a separate stdio adapter for clients that need local plugin-directory tools. It is not Otto's runtime and it is not a second hosted MCP server. A minimal local configuration is:

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

The local tool catalog includes create_plugin, add_node, update_plugin, validate_plugin, list_plugins, publish_plugin, run_workflow, and describe_node. Use explicit project or plugin paths supported by each tool. Publishing requires a registry connection and is a separate action from creating or validating a plugin. Its API-backed project tools still require OCTONODE_API_URL, OCTONODE_API_TOKEN, OCTONODE_WORKSPACE, and OCTONODE_PROJECT in the local server process.

Install the external client plugin

The Octonode Connect AI-client plugin bundles the connection skill and hosted MCP dependency. After its marketplace entry is registered in octonode-devtools, add that marketplace with:

codex plugin marketplace add nivdoron1/octonode-devtools \
  --sparse .agents/plugins \
  --sparse connect-skill-plugin
codex plugin marketplace list

Install or enable Octonode Connect in the client plugin directory, then run octonodes connect to supply authentication and project scope. This does not install an Octonode workflow plugin.

Resources and connection problems

Clients can use resources/list and resources/read to discover the bundled code-author guidance at octonode://guidance/code-author. Resource text gives the assistant instructions; it does not execute tools or grant access.

Header helper not found: install octonodes on the client's PATH or use its absolute path in http_headers_helper.
Process appears to wait: the optional local octonode mcp command waits for protocol messages; it is not an interactive shell.
Missing workspace/project: regenerate the client configuration with --workspace and --project, then reconnect.
Unauthorized tool call: verify the key using the read-only API example, then check its project binding and required action scope.