Connect Huitzo to Claude.ai (and other MCP clients)

guides mcp claude claude-desktop cursor vscode integration

Connect Huitzo to Claude.ai (and other MCP clients)

Huitzo runs a Remote MCP server at https://huitzo.ai/mcp. Any MCP client — Claude.ai, Claude Desktop, Cursor, the VS Code MCP extension — can connect, list your tenant's pack commands as native tools, and invoke them inline. Authentication is a single Huitzo API key in the Authorization: Bearer header.

This guide is for using Huitzo from an external client. If you're building a pack that calls external MCP servers from inside a command, see MCP Pack Integration instead — that's the opposite direction.

At a glance
Endpoint https://huitzo.ai/mcp
Transport Streamable HTTP (the modern MCP transport)
Auth Authorization: Bearer sk-huitzo-...
Required scope commands:execute
Tools exposed Every pack command your tenant can see (public + your private + organization-shared)

Step 1 — Generate an API key

API keys are long-lived, scoped, and revocable — exactly what a connector config needs (JWTs expire and rotating them in a connector UI is painful).

Dashboard:

  1. Open the Huitzo dashboard.
  2. Settings → API Keys → Create API key.
  3. Name it something memorable (e.g. claude-ai).
  4. Scope: tick commands:execute (the only scope an MCP client needs).
  5. Copy the key immediately — you won't see it again. It looks like sk-huitzo- followed by 64 hex characters.

You can revoke any key at any time from the same Settings page; revocation is instant.

Step 2 — Connect a client

Claude.ai

  1. Settings → Connectors → Add custom connector.
  2. Name: Huitzo (or whatever you like).
  3. URL: https://huitzo.ai/mcp
  4. Authentication: choose Bearer token. Paste your sk-huitzo-... key.
  5. Save.

Claude will list your packs as tools the next time you start a conversation. You can ask it to invoke any of them by name.

Claude Desktop / Cursor / VS Code

These clients read MCP server configs from a JSON file. Add the following block under mcpServers, replacing sk-huitzo-... with your key:

{
  "huitzo": {
    "type": "streamable-http",
    "url": "https://huitzo.ai/mcp",
    "headers": {
      "Authorization": "Bearer sk-huitzo-..."
    }
  }
}
Client Config file
Claude Desktop (macOS) ~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows) %APPDATA%\Claude\claude_desktop_config.json
Claude Code .claude/settings.json in the repo
Cursor Settings → MCP servers → Edit mcp.json
VS Code (MCP extension) The extension's MCP configuration UI; paste the same block

Restart the client after editing.

Step 3 — Use it

Open a conversation in your client and prompt naturally:

"Use the huitzo claims-v1__analyze tool to score this incoming claim."

The client picks the right tool from the list, fills in the arguments using the JSON-Schema you declared in your pack, calls the Huitzo MCP endpoint, and gets the result back inline.

Long-running commands

Most pack commands run synchronously on the fast queue — tools/call returns the result inline. A small number of commands declared with queue: medium or queue: long in the pack manifest dispatch to a background worker. For those, the MCP server returns a pending envelope instead of a result:

{
  "pending": true,
  "task_id": "celery-abc-...",
  "queue": "medium",
  "message": "Command queued on the medium pool. Poll GET /api/v1/tasks/{task_id} for the result."
}

Claude.ai (or any model in front of the MCP client) will see the message and can either tell the user to come back, or — for clients that support follow-up tool calls — poll GET /api/v1/tasks/{task_id} against the same Huitzo host using the same API key.

Tool naming

Huitzo command namespaces look like @scope/pack/command, but MCP tool names are restricted to [a-zA-Z0-9_-]+. The MCP server maps deterministically:

@huitzo/demo/echo        ↔  huitzo__demo__echo
@claims-v1/scorecard/run ↔  claims-v1__scorecard__run

Round-trip: split on __, prepend @. No information is lost.

Scope of access

A connected client sees and can invoke:

  • Every public pack command on Huitzo.
  • Every command in your tenant's private packs.
  • Every command in packs your tenant has been granted access to via an organization share.

It cannot:

  • See or call commands in other tenants' private packs.
  • Bypass the pack's declared HTTP allowlists, secret scopes, or DB allowlists.
  • Run with elevated privileges — API-key-authenticated requests run as member/free regardless of the issuing user's role, exactly like every other API-key-authenticated call.

Tenant isolation is enforced by PostgreSQL RLS on the same path the dashboard and CLI use, so the threat model is identical.

Troubleshooting

Symptom Cause Fix
401 Authentication required No Authorization header Add the Bearer header in your client config
401 ... requires API-key authentication Sent a JWT or cookie instead of an API key Generate an API key and use it as the Bearer token
401 Invalid or revoked API key Key was revoked or never existed Generate a new key in Settings → API Keys
403 ... missing 'commands:execute' scope Key authenticated but lacks the required scope Generate a new key with the commands:execute scope
Tool list is empty Tenant has no visible commands Publish a pack first (huitzo pack publish) or join an org with shared packs
Command not available in this deployment Pack version not loaded on the running backend Republish or wait for the next backend deploy cycle
Input validation error Args don't match the pack's inputSchema Inspect the schema on the tool definition; fix the call
Response says "pending": true with a task_id Command runs on the medium/long queue and dispatches asynchronously Poll GET /api/v1/tasks/{task_id} to retrieve the result

Self-hosting

If you run Huitzo on your own infrastructure, the MCP endpoint lives at the same path: https://<your-host>/mcp. Point the connector there. Auth, RLS, and tool surface are identical to the hosted offering.

See also