MCP Setup

Connect your AI client (Claude Code, Cursor, Codex, etc.) to KamuiDash via the Model Context Protocol (MCP). Once connected, your AI assistant can list projects, deploy apps, read logs, and manage DNS — all through tool calls.

Prerequisites

• A KamuiDash account (sign up at dashboard.kamui-platform.com)
• The KamuiDash CLI installed (CLI Installation)
• An AI client that supports MCP HTTP transport (Claude Code, Cursor, Codex, etc.)

The Fastest Path: kamui mcp setup

If you just want to get started, run a single command:

kamui login          # if you haven't yet
kamui mcp setup

This will:

1. Issue a long-lived Personal Access Token (PAT) for MCP use (default 365 days)
2. Print copy-pasteable setup snippets for Claude Code, Cursor, and Codex
3. Print the plaintext token to stdout (so it's pipe/redirect-friendly)

⚠️ The token is shown only once. Save it now (or pipe to a clipboard tool: kamui mcp setup | pbcopy).

Per-client Setup

Already have a token, or want to connect another client? Use:

kamui mcp config claude-code   # or: cursor, codex, all

This prints the config snippet without issuing a new token. Replace <YOUR_KAMUI_PAT> with a real token (issued via kamui mcp setup or kamui tokens create).

Claude Code

claude mcp add --transport http kamui \
  https://api.kamui-platform.com/mcp \
  --header "Authorization: Bearer kamui_pat_xxxxxxxxxxxxxxxx"

⚠️ The bearer token appears as a plain command-line argument, so it can leak into:

• shell history (~/.bash_history, ~/.zsh_history)
• terminal scrollback / shared tmux panes
• ps output briefly while the command runs

To avoid this, either prepend a space (with HISTCONTROL=ignorespace set in your shell) so the line is omitted from history, or — better — use the unattended Automation flow below, which never types the token into the shell at all. > /dev/null 2>&1 only hides stdout/stderr; it does not protect history or ps.

Restart Claude Code (or open a new session). Run /mcp inside Claude Code to confirm the server is connected.

Cursor

Edit ~/.cursor/mcp.json (create the file if it doesn't exist):

{
  "mcpServers": {
    "kamui": {
      "type": "http",
      "url": "https://api.kamui-platform.com/mcp",
      "headers": {
        "Authorization": "Bearer kamui_pat_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart Cursor. The server should appear in MCP settings.

Codex (OpenAI)

Edit ~/.codex/config.toml and add:

[mcp_servers.kamui]
url = "https://api.kamui-platform.com/mcp"
headers = { Authorization = "Bearer kamui_pat_xxxxxxxxxxxxxxxx" }

Automation / AI Agent Setup

For unattended setups (CI, headless servers, agents that drive the shell), use kamui mcp setup --register. It issues the PAT, writes it to a file with mode 600, and registers the chosen client(s) automatically — without ever printing the token to the terminal:

# Issue token, save to file, and register all clients in one shot
kamui mcp setup --register --token-file ~/.kamui/mcp-pat

# Register only a specific client
kamui mcp setup --register --token-file ~/.kamui/mcp-pat --client claude-code

This is the recommended path when an LLM agent is running the command on your behalf: the token never appears in the agent's transcript, scrollback, shell history, or ps output. The agent only ever sees the file path.

The token file is plain text — protect it the same way you would an SSH private key (don't commit it, restrict access to your user, prefer short-lived --days values for ephemeral environments).

Verify the Connection

Test the token from the terminal first. The REST endpoint is the easiest sanity check:

curl -H "Authorization: Bearer kamui_pat_xxxxxxxxxxxxxxxx" \
  https://api.kamui-platform.com/api/projects | jq

To exercise the MCP endpoint at the protocol level (instead of the REST API), call tools/list over JSON-RPC. The MCP HTTP transport requires both application/json and text/event-stream in the Accept header — this trips up most hand-rolled curl examples:

curl -N https://api.kamui-platform.com/mcp \
  -H "Authorization: Bearer kamui_pat_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A successful response includes the list of tool definitions (list_projects, get_app, …). If you get HTTP 406 / "Not Acceptable", you're missing one of the two Accept values.

If both checks pass, ask your AI client:

"List my projects on KamuiDash."

The client should call the list_projects MCP tool and return your projects.

Available MCP Tools

Once connected, your AI client can call these tools:

Token Management

Token scope (important)

Personal Access Tokens currently grant full account access — the same permissions as your logged-in user, across every project you own. There is no read-only or project-scoped variant yet (both are planned).

Practically, this means anyone holding the PAT can list, create, update, and delete any of your apps and databases. Treat each token as you would your password:

• Don't paste a PAT into a chat with a third-party AI service unless that service is itself the consumer (e.g. Claude Code reading your local config file)
• Don't commit a PAT to a repo, even a private one
• Use a short --days value for tokens issued to short-lived automation (CI runs, ephemeral agents)
• Revoke promptly when the AI agent or laptop is no longer trusted (see "I lost my laptop" below)

List your tokens

kamui tokens list

Issue another token

kamui tokens create --name "ci-deploy" --days 90

Revoke a token

kamui tokens delete <token-id>

Troubleshooting

The AI client says "MCP server failed to connect"

1. Confirm the token works with curl (see Verify the Connection)
2. Confirm your client's config has type: "http" (or transport: http for Claude Code)
3. Restart the AI client after editing the config

"401 Unauthorized" responses

Your token may have expired. Issue a new one:

kamui mcp setup

Then update your client's config with the new token.

"403 Forbidden" or "Project not found"

You're authenticated, but the project doesn't belong to your account. Confirm with kamui projects list.

I lost my laptop / the token leaked

Revoke immediately:

kamui tokens list
kamui tokens delete <token-id>

Then issue a new one and update your client's config.

Next Steps

• CLI Command Reference
• Quick Start (deploy your first app)