MCP Integration

Octipus integrates with the Model Context Protocol (MCP) as an MCP client. This allows agents to use tools exposed by external MCP servers (like Claude Code’s MCP or custom servers).

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

Configuration

Configure MCP servers through the web UI MCP page or via the API. Each server entry specifies:

Name — identifier for the server
Transport — stdio or sse
Command / URL — launch command or remote HTTP endpoint
Environment variables — any env vars to pass to stdio servers

Example: Add a Custom Stdio Server

{
  "name": "my-custom-server",
  "transport": "stdio",
  "command": "node",
  "args": ["/path/to/server.js"],
  "env": {
    "DEBUG": "true"
  }
}

Example: Add a Remote SSE Server

{
  "name": "remote-research-tools",
  "transport": "sse",
  "url": "https://api.example.com/mcp"
}

Troubleshooting

Issue	Solution
Server not discovered	Check MCP > Discover Servers in the web UI. Verify command and env vars are correct.
Tools not appearing	After connecting a server, hard-refresh the browser. Tools cache at page load.
Permission denied	Ensure the stdio command is executable and in PATH.
Connection timeout	Check the server is running and responding. For SSE, verify URL and network access.