MCP Server

The standalone mcp-server/ package exposes backend capabilities to MCP clients. It registers 88 tools across 26 groups; use MCP tools/list for the actual inventory of the build you run. Availability and results depend on backend configuration and the authenticated account.

Build and connect over stdio

cd mcp-server
npm ci
npm run build

A typical client configuration is:

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

Backend authentication

A personal access token in OCTIPUS_API_KEY is preferred. Alternatively set both OCTIPUS_USER and OCTIPUS_PASSWORD for an account without TOTP. The bridge uses /api/auth/login-mobile, validates the returned expiry, caches per backend client, and shares concurrent login attempts. TOTP accounts should use a personal token; the bridge has no interactive TOTP flow.

Credential mode refreshes and retries a backend 401 exactly once. API-key mode takes precedence and does not retry authentication failures. MASTER_KEY is an encryption key, not an API credential. Revoke old tokens explicitly in the API Tokens UI; deleting a local token file does not revoke the stored token.

Legacy HTTP/SSE

export OCTIPUS_API_KEY=octi_your_backend_token
export MCP_API_KEY=choose-a-separate-transport-key
npm run start:http
# Optional bind/port override:
npm run start:http -- --host 0.0.0.0 --port 4010

The listener defaults to 127.0.0.1:3010; --host overrides MCP_HOST. HTTP mode requires a nonempty MCP_API_KEY. Both GET /sse and POST /messages?sessionId=<id> need that key as a Bearer header. The stream advertises its POST endpoint; accepted requests return 202 and results arrive as SSE messages. Each stream owns its own protocol session, removed on disconnect.

This is the SDK’s legacy SSE transport, not Streamable HTTP /mcp. CORS_ORIGINS is an exact comma-separated allowlist, default http://localhost:3007; disallowed Origin headers receive 403. Native clients without Origin still need the key. POST bodies are SDK-bounded to 4 MB. GET /health is public and reports the listener, not backend readiness.

All HTTP clients use the same configured backend account. The shared transport key is not per-user identity. Use TLS for remote exposure and share the bridge only with clients authorized to use that account.

Permissions and tests

Direct execution is unattended: ASK returns an approval-required error rather than auto-approving. Reviewed scoped grants can authorize automation; DENY still wins. See Security.

npm test builds and runs authentication, real SDK HTTP/SSE concurrency and boundary tests, and a compiled stdio roundtrip against local fixtures. These checks do not establish live-provider quality or remote proxy compatibility.