MCP server overview

Hanzo IAM exposes a Model Context Protocol (MCP) server. Clients (e.g. AI assistants or automation tools) call it over JSON-RPC 2.0 to manage applications, users, and other resources without going through the REST surface directly.

Where the door is depends on how IAM is served, and there are exactly two cases:

/mcp is the framework default; the composed cloud binary moves it to /v1/mcp so every service shares one /v1 namespace. api.hanzo.ai/mcp answers 308 with {"error":"the MCP door moved","door":"/v1/mcp"} rather than failing silently, so a misaddressed client is told where to go.

A standalone IAM serves a 200 text/html SPA for any unregistered path, so a wrong MCP URL returns 200 HTML rather than 404. If initialize comes back as HTML, you have the wrong path — not a broken server.

What is MCP?

MCP is a JSON-RPC 2.0 protocol for discovering and calling tools provided by a server. Hanzo IAM’s MCP server exposes tools so clients can manage Hanzo IAM resources in a standard way.

Getting Started

The MCP endpoint is available at /mcp and accepts POST requests with JSON-RPC 2.0 payloads. Before making tool calls, clients must complete the initialization handshake:

POST /mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

The server responds with its capabilities:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "Hanzo IAM MCP Server",
      "version": "1.0.0"
    }
  }
}

After initialization, send a notification to indicate the client is ready:

```json
POST /mcp
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}