MCP Integration

Octipus integrates with the Model Context Protocol (MCP) in two ways: as an MCP client that connects to external MCP servers, and as an MCP server that exposes its capabilities to external tools.

MCP Client Bridge

The client bridge connects to external MCP servers and makes their tools available to agents.

Supported Transports

Transport	Description
Stdio	Subprocess-based MCP servers — spawns a local process
SSE	HTTP Server-Sent Events for remote MCP servers

Capabilities

Tool discovery: Automatically enumerates tools from connected servers
Resource discovery: Lists available resources
Prompt discovery: Lists available prompt templates
Dynamic loading: MCP servers can be added and removed at runtime

Configure MCP servers through the web UI MCP page or via the API.

MCP Server (octipus-mcp-server)

The mcp-server/ package exposes Octipus’s capabilities as MCP tools for external CLI models like Claude Code and Gemini CLI.

Available Tools (28)

Category	Tool	Description
Search	`octipus_search`	Search the web via SearXNG
	`octipus_fetch_page`	Fetch and extract text from a URL (browser-rendered)
Agents	`octipus_list_agents`	List running agents with status
	`octipus_spawn_agent`	Spawn a new autonomous agent
	`octipus_stop_agent`	Stop a running agent
	`octipus_send_message`	Send a message to a running agent
	`octipus_get_agent_events`	Get agent events (polling with cursor)
Sessions	`octipus_list_sessions`	List recent chat sessions
	`octipus_get_messages`	Get messages from a session
Models	`octipus_list_models`	List available AI models
	`octipus_model_health`	Get model health status
Chat	`octipus_chat`	Send a message through the orchestrator
Experts	`octipus_list_experts`	List available expert personas
	`octipus_chat_with_expert`	Chat using a specific expert (bypass orchestrator)
Tools	`octipus_list_tools`	List all available tools and their actions
	`octipus_execute_tool`	Execute any tool action (filesystem, shell, git, docker, etc.)
Skills	`octipus_list_skills`	List domain knowledge skills
	`octipus_get_skill`	Get skill details
	`octipus_create_skill`	Create a custom skill
	`octipus_update_skill`	Update an existing skill
	`octipus_delete_skill`	Delete a skill
Knowledge	`octipus_search_knowledge`	Semantic search across indexed documents
	`octipus_index_file`	Index a file for semantic search
Hooks	`octipus_list_recurring_tasks`	List hooks and scheduled tasks
	`octipus_create_recurring_task`	Create a hook or scheduled task
	`octipus_update_recurring_task`	Update a hook or task
	`octipus_delete_recurring_task`	Delete a hook or task
	`octipus_toggle_hook`	Enable or disable a hook

Setup

Build the MCP server:

cd mcp-server && npm install && npm run build

Add to .mcp.json at your project root:

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

Add to .gemini/settings.json:

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

Authentication

The MCP server supports two authentication methods:

Method	Environment Variables	Description
API Key	`OCTIPUS_API_KEY`	Direct JWT or MASTER_KEY token
User/Password	`OCTIPUS_USER`, `OCTIPUS_PASSWORD`	Auto-login with JWT caching

Tool Execution Bridge

The MCP server uses the tool execution API endpoint to bridge tool calls:

POST /api/tools/:toolId/tools/:toolName/execute

This allows external CLI models to execute any tool through the MCP protocol, with full permission enforcement and audit logging.