Skip to content
AM

Quickstart: direct HTTP MCP

Use this page when you are implementing an MCP client yourself instead of using an IDE bridge.

Prerequisites

  • A ZITADEL bearer token accepted by InBlack.
  • An InBlack tenant ID.
  • An HTTP client that can send JSON-RPC POST requests.

Endpoint

https://ai-coo.inblack.app/mcp

The public MCP endpoint is stateless streamable HTTP. It accepts JSON-RPC POST requests only. Send Authorization on every request and, after organization selection, send X-Tenant-ID on every request.

Authorization: Bearer <zitadel-access-token>
X-Tenant-ID: <tenant-id>
Content-Type: application/json

The dedicated alias https://mcp.inblack.app/mcp is equivalent. Legacy /sse and /messages paths return 410 legacy_sse_retired.

Discover the manifest

Terminal window
curl https://ai-coo.inblack.app/mcp/manifest \
  -H "Authorization: Bearer <zitadel-access-token>" \
  -H "X-Tenant-ID: <tenant-id>"

The manifest is filtered by the principal and tenant policy. It includes schema_version, canonical_catalog, surface, transport, auth, counts by kind and pillar, and a tools array with per-tool metadata.

Initialize

Terminal window
curl https://ai-coo.inblack.app/mcp \
  -H "Authorization: Bearer <zitadel-access-token>" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": { "tools": {} },
      "clientInfo": { "name": "my-agent", "version": "0.1.0" }
    }
  }'

List tools

Terminal window
curl https://ai-coo.inblack.app/mcp \
  -H "Authorization: Bearer <zitadel-access-token>" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

The response contains only tools visible to the current surface, tenant policy, role, entitlements, AI COO scope, and persona.

Call a tool

Terminal window
curl https://ai-coo.inblack.app/mcp \
  -H "Authorization: Bearer <zitadel-access-token>" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "inblack_list_accounts",
      "arguments": { "limit": 5 }
    }
  }'

Tool results are JSON-serialized in MCP content text. The underlying tool result includes a status, tier, summary, and optional data, warning, preview, pending_action_id, or error_code.

Select an organization first

If your client does not know the tenant ID yet, call bootstrap-visible organization tools first. When inblack_set_org succeeds, the Worker includes:

{
  "next_request_headers": {
    "X-Tenant-ID": "tenant_..."
  }
}

Send that header on subsequent requests.

Internal surface

The internal surface is:

https://ai-coo.inblack.app/internal/mcp

It requires a service token or a ZITADEL token with inblack:mcp:internal, mcp:internal, or the mcp_internal role. It is for InBlack platform callers, not external customer code.