Connecting Claude

Pick your path

Both paths talk to the same MCP server and unlock the same container tools. The only difference is where the connection lives.

Connect from Claude.ai

This is the fastest path for everyday use. After approving the connector once, every new Claude conversation can launch your container, run bash, manage secrets, and tweak tool config.

1. Open claude.ai → Settings → Connectors and click Add custom connector.
2. Fill in the three fields exactly as shown in your CloudClawer Settings → Connect tab:
   • Server name: CloudClawer
   • MCP server URL: https://api.cloudclawer.com/mcp
   • Client ID: shown on the Connect tab (different for dev vs. prod)
3. Approve the OAuth prompt when Claude redirects you.
4. In a new conversation, ask Claude to call a CloudClawer tool — e.g. "Use CloudClawer to launch a container and run uname -a."

Connect from a terminal

Install the CLI globally and run the browser-based init flow. It writes an API key to~/.cloudclawer with mode 0600.

npm install -g cloudclawer
cloudclawer init

cloudclawer initopens your browser to approve the new key, then drops you into a setup wizard. Once it's done, the CLI can talk to your container directly:

cloudclawer launch
cloudclawer wait
cloudclawer bash "echo hello from your agent"

If you ever need to rotate or revoke the key:

cloudclawer apikey create   # rotate (invalidates the previous key)
cloudclawer apikey revoke   # revoke without replacement
cloudclawer apikey status   # check whether a key is configured

Using the CLI as a stdio MCP server

The npm package also ships a local stdio MCP server (mcp-server.js). Point Claude Code at it by adding this to ~/.claude/settings.json:

{
  "mcpServers": {
    "cloudclawer": {
      "command": "node",
      "args": ["${HOME}/.npm-global/lib/node_modules/cloudclawer/mcp-server.js"]
    }
  }
}

It reads CLOUDCLAWER_KEY from ~/.cloudclawer (written by cloudclawer init), so no header config is required.

Authentication

The hosted MCP server (https://api.cloudclawer.com/mcp) authenticates the Claude.ai connector via OAuth — there is no static Bearer token to manage. The CLI and the local stdio MCP instead use a long-lived API key stored at ~/.cloudclawer and sent as an X-API-Key header.

Keep one key per machine. Rotating a key with cloudclawer apikey create immediately invalidates the previous one, so update other machines before rotating.

Tools the connector exposes

Once connected, Claude can call these CloudClawer tools. The exact tool names match what Claude sees in the MCP tool list.

Verifying the connection

After connecting, ask Claude to list the CloudClawer tools and call a cheap one:

"Use CloudClawer to check container status, then run `uname -a` in bash."

You should see Claude call status (and launch + wait if no container is assigned yet), then bash. The container log line will also appear in your routines log.

Troubleshooting

• Connector shows "disconnected" in Claude.ai: open it and re-approve the OAuth prompt. Tokens expire if your CloudClawer session expires.
• cloudclawer bash hangs: the container may have been spot-evicted. Run cloudclawer status; if it reports "not assigned", call cloudclawer launch followed by cloudclawer wait.
• Invalid API key: rotate with cloudclawer apikey create — the wizard writes the new key to ~/.cloudclawer.
• Wrong environment: the Client ID and OAuth endpoint differ between dev and prod. Always copy values from your Settings → Connect tab.