Skip to main content

MCP (Model Context Protocol) Services

The OctoMesh MCP (Model Context Protocol) Services is the Model Context Protocol server for OctoMesh. It exposes the platform's full administrative surface — tenants, identity, blueprints, communication adapters, time-series archives, generic Construction Kit entity CRUD, and aggregation queries — as ~177 typed tools that AI assistants (Claude Code, Claude Desktop, and any other MCP-capable client) call over HTTP+SSE.

Conceptually, it gives an AI agent the same reach an operator has with octo-cli, plus direct access to the runtime engine for entity queries and aggregations that would otherwise require GraphQL.

When to use it​

You want to…Use
Drive OctoMesh from an AI assistant (Claude Code / Claude Desktop)MCP Services
Drive OctoMesh from a human terminal or a CI pipelineocto-cli
Drive OctoMesh from your own application codeOcto SDK
Query data interactively through a UIRefinery Studio or Power BI

The MCP Services, the CLI, the SDK, and the Studio all talk to the same backend services. Anything you can do through one, you can do through the others — the MCP Services is the one optimised for AI consumption.

How it fits together​

Three families of tools live in the server:

  1. Platform-admin tools (~140) wrap the same backend SDK clients that octo-cli uses. Calling create_tenant from the MCP Services is byte-for-byte equivalent to running the matching octo-cli command.
  2. Generic CK CRUD + schema tools (~16) give an AI agent universal entity query/create/update/delete for any Construction Kit type without composing GraphQL.
  3. Aggregation + stream-data query tools (~10) mirror the asset-repository's GraphQL transient-query surface — scalar and grouped aggregations, time-bucket downsampling, persisted-query replay.

Binary payloads (tenant dumps, CK model imports, runtime model exports) flow through a separate /file-transfer/{upload,download}/{id} channel so multi-GB files don't go through JSON-RPC.

What's in this section​

  • Getting started — Register the server with Claude Code or Claude Desktop, complete the OAuth Device Flow, make your first tool call.
  • Tool reference — The ~177 tools grouped by family, with a one-line description per tool.
  • Deployments — Hosted endpoints (prod-1, prod-2) and how to register each.
  • Troubleshooting — Authentication, token refresh, common error messages.

For local development of the MCP Services itself — building from source, configuring backend service URLs, running against Start-Octo — see MCP Services development in the Developer Guide.

Key properties​

  • HTTP+SSE transport. Register with claude mcp add --transport http …. No stdio shim required.
  • Stateless multi-tenant. Tenant comes from the tool parameter tenantId (preferred) or the URL path /{tenantId}/mcp. No tenant is stored on the session.
  • OAuth2 Device Authorization Flow. Call authenticate(tenantId), complete the browser login, call check_auth_status. Tokens auto-refresh.
  • Destructive operations gated. Every delete/destroy/rollback tool requires an explicit confirm: true parameter. There is no interactive prompt.
  • Risk metadata for safety gates. Tools carry an [McpRisk(Low|Medium|High)] classification (read via get_tool_risk_metadata) so wrapping clients like the OctoMesh AI Adapter can route high-risk calls through user approval.
  • Per-call tenant routing. One registered server, many tenants — no need for one MCP Services registration per tenant.