Skip to main content

Getting started

This page walks you through registering the MCP (Model Context Protocol) Services with an AI client and making your first authenticated tool call. The hosted endpoints are listed on the Deployments page.

Step 1 — Register the server with your AI client​

You only need to register once. The same registration handles every tenant; tenant routing happens per tool call.

Claude Code (CLI)​

Claude Code 1.0+ speaks HTTP MCP natively. Register with claude mcp add:

# Generic form — replace mcp.example.com with the hosted URL for your cluster
claude mcp add --transport http --scope user octomesh https://mcp.example.com/mcp

# Production examples
claude mcp add --transport http --scope user octomesh-prod-1 https://mcp.prod-1.octo-mesh.com/mcp
claude mcp add --transport http --scope user octomesh-prod-2 https://mcp.prod-2.octo-mesh.com/mcp

Scope options:

ScopeEffectGood for
--scope userAvailable in every projectRemote / shared endpoints
--scope localOnly in the current projectProject-specific endpoints
--scope projectCommitted to .mcp.json in the repoTeams sharing the same remote MCP

Verify the registration:

claude mcp list
# octomesh:         https://mcp.example.com/mcp            (HTTP) - ✓ Connected
# octomesh-prod-1:  https://mcp.prod-1.octo-mesh.com/mcp   (HTTP) - ✓ Connected

Restart your Claude Code session so the tool catalogue is enumerated.

Claude Desktop​

Claude Desktop also supports HTTP MCP via its config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "octomesh": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    },
    "octomesh-prod-1": {
      "type": "http",
      "url": "https://mcp.prod-1.octo-mesh.com/mcp"
    }
  }
}

Each registration gets its own tool namespace inside Claude Desktop — mcp__octomesh__*, mcp__octomesh-prod-1__* — so you can have several environments side-by-side. Restart the desktop app after editing the file.

Step 2 — Authenticate (OAuth2 Device Flow)​

The server uses OAuth2 Device Authorization. The client never sees your password; you log in once in a browser, the server stores tokens per MCP session and refreshes them automatically.

Ask your AI assistant to call authenticate:

Authenticate me to tenant my-tenant.

The tool returns a verification URL and a user code. Open the URL in your browser, enter the code, and complete the login. Then ask the assistant to call check_auth_status — it confirms the session is authenticated and stores the tokens.

Equivalent raw JSON-RPC:

{ "tool": "authenticate",       "parameters": { "tenantId": "my-tenant" } }
// → { verificationUri: "https://identity.…/device", userCode: "XXXX-YYYY", ... }

{ "tool": "check_auth_status",  "parameters": {} }
// → { isAuthenticated: true, expiresInSeconds: 3600, ... }

octo-mcpServices-device is the Identity Server client used for this flow; it is registered automatically on server startup.

Step 3 — Make your first call​

Anything you can do with octo-cli you can ask the assistant to do in natural language. Three good first calls:

Who am I?

Who am I logged in as?

Calls whoami and returns your name, email, roles, and the tenants you have access to.

Which tenants can I administer?

List my tenants.

Calls list_tenants. Useful before you start running tenant-scoped tools.

List installed blueprints in a tenant:

List all installed blueprints in tenant acme.

Calls list_blueprint_installations with tenantId: "acme".

Step 4 — Understand tenant routing​

The server is stateless with respect to tenants. Every tenant-scoped tool accepts an optional tenantId parameter, resolved in this priority order:

  1. Tool parameter tenantId (explicit, preferred)
  2. URL path segment on the legacy /{tenantId}/mcp endpoint (backwards-compatible)
  3. Error if neither is supplied

Best practice: register one server URL — /mcp (tenantless) — and pass tenantId per call. That lets a single session move between tenants in one conversation.

Step 5 — Destructive operations need confirm: true​

There is no interactive prompt over MCP. Every delete/destroy/rollback/uninstall tool refuses to run unless you pass confirm: true. Example:

{
  "tool": "delete_tenant",
  "parameters": {
    "tenantId": "octosystem",
    "childTenantId": "scratch-tenant",
    "confirm": true
  }
}

Without confirm: true the call returns IsSuccess: false and ErrorMessage: "Refusing to delete '...' without confirm=true." AI assistants are trained to read this and ask you first — exactly the desired behaviour.