Quickstart: Claude Desktop

InBlack’s public MCP endpoint currently accepts ZITADEL bearer tokens but does not yet implement the complete MCP OAuth authorization-server flow required by Claude’s native remote connectors. Until that runtime ships, connect Claude Desktop through a local stdio bridge that sends the bearer and tenant headers explicitly.

Prerequisites

Claude Desktop with local MCP server support.
Node.js 18 or newer and npx.
A ZITADEL access token accepted by InBlack.
The InBlack tenant ID to use.

The bearer token is short-lived. This transitional configuration must be updated when the token expires.

Configure the bridge

Open claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add a local server entry:

{
  "mcpServers": {
    "inblack": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://ai-coo.inblack.app/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${INBLACK_AUTH_HEADER}",
        "--header",
        "X-Tenant-ID:${INBLACK_TENANT_ID}"
      ],
      "env": {
        "INBLACK_AUTH_HEADER": "Bearer <zitadel-access-token>",
        "INBLACK_TENANT_ID": "<tenant-id>"
      }
    }
  }
}

This uses mcp-remote only as a local stdio-to-streamable-HTTP bridge. The headers bypass its OAuth client behavior because the current InBlack endpoint expects an already-issued bearer token.

Protect the configuration as a secret-bearing file. Do not commit or share it. Completely restart Claude Desktop after editing it.

Verify discovery

Ask Claude:

List the InBlack tools available for this tenant.

The returned set is filtered by tenant policy and your principal. It is not necessarily the complete 440-tool source catalog.

Next, call a low-risk read such as listing accounts with a small limit. For writes, start with the matching inblack_simulate_* tool and handle INBLACK_CONFIRMATION_REQUIRED from the real write.

Pending actions can be approved or rejected by calling inblack_confirm_action. Accounting also exposes its current pending-action queue in the Accounting application; do not use the obsolete portal.inblack.app/pending-actions path.

Change tenant

Replace INBLACK_TENANT_ID with the new tenant ID, restart the bridge, and rediscover tools. The bearer principal must be authorized for the selected tenant; X-Tenant-ID does not grant membership by itself.

Troubleshooting

Symptom	Check
Bridge does not start	Run `node --version` and `npx --version`; inspect Claude’s local MCP logs
`missing_bearer_token`	Confirm the `Authorization` header argument and environment value
`invalid_bearer_token`	Replace an expired token and confirm it was issued for the configured InBlack audience
`tenant_policy_unavailable`	Confirm the tenant ID, membership, and tenant AI policy
Tool is absent	Check surface, AI COO scope, pillar, feature, GL layer, entitlement, role, permission, and persona gates
Legacy transport error	Use `/mcp` with `http-only`; `/sse` and `/messages` are retired

Native connector status

Claude’s Settings > Connectors flow is the preferred long-term remote setup, but it supports authenticated connectors through MCP OAuth. Adding the current InBlack URL there will not replace the explicit bearer-token setup above. This page should move to the native flow only after the InBlack OAuth runtime is deployed.