Connect Claude Code over MCP

quickstart mcp claude-code cursor integration

Connect Claude Code over MCP

Once your tenant has a pack, this takes about five minutes: Claude Code calls your pack commands as tools. This page is the short path. Connect Huitzo to Claude Code, Cursor and other MCP clients is the full reference. For the opposite direction, a pack calling external MCP servers, see MCP Pack Integration.

The server URL is https://huitzo.ai/mcp. The trailing-slash form https://huitzo.ai/mcp/ works the same.

1. Check the prerequisites

  • A Huitzo account at huitzo.ai, or your own deployment (use https://<your-host>/mcp/).
  • At least one pack command your tenant can see. The server lists those commands plus huitzo_task_poll, so with none you get only huitzo_task_poll. If you have no pack yet, publish one first.
  • Developer Mode on (Hub → Settings → Developer). The API Keys card appears only then; see Accounts & Developer Mode.
  • Claude Code installed.

2. Create an API key

In the Hub: Settings → Developer → API Keys → Create MCP API Key. The key carries the commands:execute scope, the only one an MCP client needs. Copy it now; it is shown once. It starts with sk-huitzo-.

3. Add the server

Pick one:

Option What it does
huitzo mcp setup docs --write The Huitzo CLI mints the key for you and writes it into Claude Code's user config (~/.claude.json) as huitzo-docs. It needs the CLI and huitzo login. Skip step 2.
claude mcp add Registers the server with the key you copied. Add --scope user to use it in every project.
.mcp.json in a repo Shares the server with a team. Each person keeps their own key in an environment variable, so the file can be committed without it.

The claude mcp add form:

claude mcp add --transport http huitzo https://huitzo.ai/mcp/ \
  --header "Authorization: Bearer <your sk-huitzo- key>"

The .mcp.json form, at the repository root:

{
  "mcpServers": {
    "huitzo": {
      "type": "http",
      "url": "https://huitzo.ai/mcp/",
      "headers": { "Authorization": "Bearer ${HUITZO_API_KEY}" }
    }
  }
}

Claude Code expands ${HUITZO_API_KEY} from the environment when it starts, so the key never lands in git.

Cursor takes the same server entry under mcpServers in ~/.cursor/mcp.json; put the key in the header yourself.

4. Restart and verify

Restart Claude Code, then check the connection:

  • claude mcp list checks each server. The entry you added (huitzo, or huitzo-docs if the CLI or the Hub's snippet made it) should read Connected.
  • Inside a session, /mcp shows the server and its tools: one per pack command your tenant can see, named scope__pack__command, plus huitzo_task_poll.

5. Run a command

Ask for it in plain words:

"List the Huitzo tools you have, then run <scope>__<pack>__<command> with …"

Claude picks the tool, fills in the arguments from the command's input schema, and shows the result inline. A command on a medium or long queue answers with a task_id first; Claude then polls it with huitzo_task_poll.

6. Troubleshooting

Symptom Fix
Not connected Check the URL is https://huitzo.ai/mcp (or your host's /mcp) and the Bearer key is valid.
401 The header is missing, or the key was revoked. Create a new key and update the header.
403 ... missing 'commands:execute' scope The key was made without the scope. Use Create MCP API Key.
Connected, but only huitzo_task_poll is listed Your tenant sees no commands. Publish a pack, or join an organization that shares one.
insufficient_credits The account has too few credits for the call; the result names required and available. Add credits, then retry. See Insufficient Credits Error.
Input validation error The arguments do not match the command's input schema. Ask Claude to read the tool's schema and retry.

More cases, and the other clients, are in the full guide.