MCP 設定

透過 Model Context Protocol (MCP) 把你的 AI 用戶端（Claude Code、Cursor、Codex 等）連接到 KamuiDash。連接完成後，你的 AI 助理就能透過工具呼叫列出專案、部署應用程式、讀取記錄與管理 DNS。

事前準備

一個 KamuiDash 帳號（可在 dashboard.kamui-platform.com 註冊）
已安裝 KamuiDash CLI（CLI 安裝）
支援 MCP HTTP transport 的 AI 用戶端（Claude Code、Cursor、Codex 等）

最快的方式：`kamui mcp setup`

如果你只想趕快開始，執行一行指令就好：

kamui login          # 還沒登入的話
kamui mcp setup

這會做以下幾件事：

核發一組供 MCP 使用的長期個人存取權杖（PAT，預設 365 天）
印出可直接複製貼上的 Claude Code、Cursor、Codex 設定片段
將明文權杖輸出到 stdout（方便搭配 pipe / 重新導向使用）

⚠️ 權杖只會顯示一次。請立即保存（或用剪貼簿工具接收：kamui mcp setup | pbcopy）。

各用戶端的設定

已經有權杖，或想再連接另一個用戶端？請使用：

kamui mcp config claude-code   # 或：cursor、codex、all

這只會印出設定片段，不會核發新的權杖。請把 <YOUR_KAMUI_PAT> 換成實際的權杖（由 kamui mcp setup 或 kamui tokens create 核發）。

Claude Code

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

⚠️ bearer 權杖會以明文出現在命令列引數中，因此可能外洩到：

shell 歷史紀錄（~/.bash_history、~/.zsh_history）

終端機的捲動紀錄／共用的 tmux 分頁

指令執行期間短暫出現在 ps 的輸出中

要避免這種情況，可以在指令前面加一個空格（並在 shell 中設定 HISTCONTROL=ignorespace），讓該行不會進入歷史紀錄；或者更好的做法是使用下方的自動化流程，它完全不會把權杖打進 shell。> /dev/null 2>&1 只會隱藏 stdout/stderr，並不會保護歷史紀錄或 ps。

重新啟動 Claude Code（或開啟新的工作階段）。在 Claude Code 中執行 /mcp 可確認伺服器是否已連上。

Cursor

編輯 ~/.cursor/mcp.json（檔案不存在就建立一個）：

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

重新啟動 Cursor。伺服器應該會出現在 MCP 設定中。

Codex (OpenAI)

編輯 ~/.codex/config.toml 並加入：

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

自動化 / AI 代理的設定

若是無人值守的環境（CI、無介面的伺服器、會操作 shell 的代理），請使用 kamui mcp setup --register。它會核發 PAT、以 600 權限寫入檔案，並自動註冊所選的用戶端 — 全程不會把權杖印到終端機上：

# 一次完成：核發權杖、存成檔案、註冊所有用戶端
kamui mcp setup --register --token-file ~/.kamui/mcp-pat

# 只註冊特定的用戶端
kamui mcp setup --register --token-file ~/.kamui/mcp-pat --client claude-code

當指令是由 LLM 代理代替你執行時，建議使用這個方式：權杖不會出現在代理的對話紀錄、捲動紀錄、shell 歷史或 ps 輸出中，代理看到的自始至終只有檔案路徑。

權杖檔案是純文字 — 請像對待 SSH 私鑰一樣保護它（不要 commit 進儲存庫、限制只有你自己能存取；對於暫時性的環境，請使用較短的 --days 值）。

確認連線

請先在終端機測試權杖。用 REST 端點做基本檢查最簡單：

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

若要在協定層級測試 MCP 端點（而非 REST API），可以透過 JSON-RPC 呼叫 tools/list。MCP HTTP transport 要求 Accept 標頭同時包含 application/json 與 text/event-stream — 大多數自己手寫的 curl 範例都會在這裡卡住：

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"}'

成功的回應會包含工具定義的清單（list_projects、get_app…）。如果收到 HTTP 406 /「Not Acceptable」，代表你少了那兩個 Accept 值其中之一。

兩項檢查都通過後，就可以問你的 AI 用戶端：

「列出我在 KamuiDash 上的專案。」

用戶端應該會呼叫 list_projects 這個 MCP 工具，並回傳你的專案。

可用的 MCP 工具

連接完成後，你的 AI 用戶端可以呼叫這些工具：

工具	功能
`list_projects`	列出你擁有的所有專案
`get_project`	取得單一專案的詳細資訊（應用程式、資料庫、計費）
`create_project`	建立新專案
`get_app`	取得應用程式的詳細資訊（網址、規格、狀態等）
`get_app_logs`	讀取應用程式的執行記錄
`list_deploy_runs`	列出部署歷史
`get_deploy_run_logs`	讀取特定部署的詳細記錄
`create_app`	從 GitHub 儲存庫建立新的 Web Server 應用程式
`create_static_app`	從 GitHub 儲存庫建立新的 Web Page 應用程式

權杖管理

權杖的權限範圍（重要）

個人存取權杖目前擁有完整的帳號存取權 — 權限等同於你登入後的使用者，涵蓋你擁有的所有專案。目前還沒有唯讀或限定專案的版本（兩者都在規劃中）。

實際上這表示，任何持有該 PAT 的人都能列出、建立、更新與刪除你的任何應用程式與資料庫。請把每一組權杖都當成你的密碼看待：

不要把 PAT 貼到第三方 AI 服務的對話中，除非該服務本身就是使用者（例如 Claude Code 讀取你本機的設定檔）
不要把 PAT commit 進儲存庫，即使是私有儲存庫也一樣
核發給短期自動化流程（CI 執行、暫時性代理）的權杖，請使用較短的 --days 值
當 AI 代理或筆電不再可信任時，請立即撤銷（見下方「筆電遺失了」）

列出你的權杖

kamui tokens list

核發另一組權杖

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

撤銷權杖

kamui tokens delete <token-id>

疑難排解

AI 用戶端顯示「MCP server failed to connect」

用 curl 確認權杖可以正常運作（見確認連線）
確認用戶端設定中有 type: "http"（Claude Code 則是 transport: http）
編輯設定後重新啟動 AI 用戶端

回應「401 Unauthorized」

你的權杖可能已過期，請核發新的一組：

kamui mcp setup

接著用新的權杖更新用戶端的設定。

「403 Forbidden」或「Project not found」

你已通過驗證，但該專案不屬於你的帳號。請用 kamui projects list 確認。

筆電遺失了 / 權杖外洩了

請立即撤銷：

kamui tokens list
kamui tokens delete <token-id>

接著核發新的一組並更新用戶端的設定。

下一步

CLI 指令參考
快速開始（部署你的第一個應用程式）