MCP Server

The standalone MCP server (mcp-server/) in Node.js exposes Octipus capabilities as MCP tools for external CLI models. External tools like Claude Code and Gemini CLI can then call these tools to:

• Search the web and fetch pages
• Spawn and manage agents
• Execute filesystem, shell, git, Docker tools
• Manage recurring tasks and automations
• Access knowledge base and semantic search
• And more — 22 tool modules with 59+ individual tools

Available Tools (59+)

Tools are organized by module. Each module exposes 1–5 individual tools:

Module	Tools
Search	octipus_search, octipus_fetch_page
Agents	octipus_list_agents, octipus_spawn_agent, octipus_stop_agent, octipus_send_message, octipus_get_agent_events
Sessions	octipus_list_sessions, octipus_get_messages
Models	octipus_list_models, octipus_model_health
Chat	octipus_chat
Experts	octipus_list_experts, octipus_chat_with_expert
Tools	octipus_list_tools, octipus_execute_tool
Skills	octipus_list_skills, octipus_get_skill, octipus_create_skill, octipus_update_skill, octipus_delete_skill
Knowledge	octipus_search_knowledge, octipus_index_file
Recurring Tasks	octipus_list_recurring_tasks, octipus_create_recurring_task, octipus_update_recurring_task, octipus_delete_recurring_task
Hooks	octipus_toggle_hook
Plus 11 more	Profiles, Messaging, Pipelines, Documents, Settings, Gateway, Health, Audit, Artifacts, Plugins, etc.

See mcp-server/src/tools/ for the full list.

Setup

1. Build the MCP Server

cd mcp-server
npm install
npm run build

2. Configure Your CLI Tool

Claude Code

Add to .mcp.json at your project root:

{
  "mcpServers": {
    "octipus": {
      "command": "node",
      "args": ["/path/to/octipus/mcp-server/dist/index.js"],
      "env": {
        "OCTIPUS_URL": "http://localhost:3005",
        "OCTIPUS_API_KEY": "<your-api-key>"
      }
    }
  }
}

Gemini CLI

Add to .gemini/settings.json:

{
  "mcpServers": {
    "octipus": {
      "command": "node",
      "args": ["/path/to/octipus/mcp-server/dist/index.js"],
      "env": {
        "OCTIPUS_URL": "http://localhost:3005",
        "OCTIPUS_API_KEY": "<your-api-key>"
      }
    }
  }
}

3. Authentication

The MCP server uses one of these authentication methods:

Method	Environment Variables	Description
API Key	OCTIPUS_API_KEY	Personal octi_… token, or the mcp-bootstrap token at ~/.octipus/mcp-token
User/Password	OCTIPUS_USER, OCTIPUS_PASSWORD	Auto-login with JWT caching

Zero-Config Bootstrap (Recommended)

On first startup of Octipus, the backend auto-generates a bootstrap token and saves it to ~/.octipus/mcp-token (mode 600). The bin/octi CLI reads this file and auto-configures .mcp.json.

To rotate the token:

rm ~/.octipus/mcp-token
octi restart

Per-User Tokens (Multi-User Setups)

For multiple users on one host, each person should mint their own token in Settings → API Tokens and set OCTIPUS_API_KEY per shell session.

Example: Browser Extension via MCP

CLI models can interact with your real browser through the MCP bridge:

# From Claude Code or Gemini CLI
octipus_execute_tool(tool_id="browser-ext", tool_name="get_tabs", args={})
octipus_execute_tool(tool_id="browser-ext", tool_name="screenshot", args={})
octipus_execute_tool(tool_id="browser-ext", tool_name="navigate", args={"url": "https://example.com"})

Requires the Browser Extension to be installed and connected.

Remote HTTP Transport

Run the MCP server as a standalone HTTP service (instead of spawning a subprocess):

node mcp-server/dist/index.js --transport http --port 3010

Then point your CLI tool to http://localhost:3010 (for local) or a remote URL.

Troubleshooting

Issue	Solution
Connection refused	Ensure Octipus backend is running on the URL specified in OCTIPUS_URL.
401 Unauthorized	Check OCTIPUS_API_KEY is a valid token. Regenerate if needed: rm ~/.octipus/mcp-token && octi restart.
Tools not discovered	Verify MCP server process is running. Check .mcp.json syntax. Hard-refresh CLI tool.
Permission denied executing tool	Use /status in web UI to check your user role and permissions.