MCP セットアップ

Nolto は /mcp に HTTP transport の MCP サーバー を公開しています。Claude Code、Codex、Cursor、Claude Desktop などの MCP クライアントから、プロジェクト管理やプラン登録を直接操作できます。

認証は OAuth 2.1 + PKCE で自動的に処理されます。初回接続時にブラウザで承認するだけで利用を開始できます。

Claude Code

claude mcp add --transport http nolto https://nolto.app/mcp

追加後、MCP ツールを使う操作（例:「プロジェクト一覧を表示して」）を行うと、ブラウザが開いて OAuth 同意画面が表示されます。承認すると、トークンが Claude Code に保存され、以降は自動的に認証されます。

動作確認

> Nolto のプロジェクト一覧を見せて

Claude Code が list_projects ツールを呼び出し、参加中のプロジェクトが表示されれば成功です。

Claude Code プラグイン

MCP サーバー設定と 4 つのスキル（プラン登録・進捗報告・ステータス確認）を一括でインストールするプラグインも利用できます。

/plugin marketplace add uruca-kk/nolto-plugin
/plugin install nolto@nolto

スキルの使い方や認証フローなど、詳細は Claude Code プラグインガイドを参照してください。

Codex CLI

codex mcp add nolto --url https://nolto.app/mcp
codex mcp login nolto

codex mcp login でブラウザが開き、OAuth 同意フローに進みます。

MCP サーバー設定と 4 つのスキル（プラン登録・進捗報告・ステータス確認）を一括でインストールするプラグインも利用できます: codex plugin marketplace add uruca-kk/nolto-codex-plugin → codex plugin add nolto@nolto. 詳細は Codex CLI プラグインガイドを参照してください。

Cursor

Cursor は MCP サーバーを ~/.cursor/mcp.json（またはプロジェクトの .cursor/mcp.json）の mcpServers で設定します:

{
  "mcpServers": {
    "nolto": { "url": "https://nolto.app/mcp" }
  }
}

初回にツールを呼び出すと、Cursor ネイティブの OAuth 同意画面がブラウザで開きます。Cursor は MCP ツールを mcp_nolto_<tool> として公開します。

MCP サーバー設定・4 つのスキル・Stop フックをまとめて配置するプラグインも利用できます（scripts/install.sh で ~/.cursor/ または .cursor/ にマージ配置）。詳細は Cursor プラグインガイドを参照してください。

Claude Desktop

Claude Desktop の設定で、MCP サーバーとして以下を追加します:

Transport: HTTP
URL: https://nolto.app/mcp

初回アクセス時にブラウザで OAuth 認証が行われます。

デフォルトプロジェクトの設定

ほとんどの MCP ツールは projectId パラメータを受け取りますが、毎回指定するのは面倒です。set_default_project ツールでデフォルトプロジェクトを設定すると、projectId を省略できます。

> デフォルトプロジェクトを my-app に設定して

MCP クライアントが set_default_project を呼び出し、以降の操作ではそのプロジェクトが自動的に使われます。

ヘッドレス / リモート環境

SSH 越しのリモートサーバーやコンテナ・CI など、ブラウザを開けない環境では OAuth のループバックコールバックが使えません（Claude Code の「Authenticate」ボタンを押しても開くブラウザがありません）。そのような場合は以下のいずれかの方法を使ってください。

推奨: `nolto login`（device-code フロー）

@nolto/cli（>= 0.3.0）の nolto login は、ヘッドレス向けの device-code 認証です。別の端末（スマホ・ラップトップ）のブラウザで承認するだけで、トークンの手動コピーは不要です。

npm install -g @nolto/cli
nolto login --client claude   # cursor / codex も指定可

表示された URL を任意の端末のブラウザで開いて承認すると、CLI が自動でトークンを取得し、--client で指定したクライアントの MCP 設定に登録します（Claude Code は claude mcp add（user scope）、Cursor は ~/.cursor/mcp.json、Codex は codex mcp add）。登録後、クライアントを再接続すれば nolto MCP ツールが使えます。

ℹ️

プラグイン同梱の nolto（plugin:nolto:nolto）はブラウザ OAuth 前提です。ヘッドレスでは「Authenticate」では完了できないため、上記 nolto login で登録した nolto サーバーを使ってください。

代替: Personal API Token をベアラーで渡す

設定 > API トークンでトークンを発行し、--header オプションで渡します。

claude mcp add --transport http nolto https://nolto.app/mcp \
  --header "Authorization: Bearer nolto_user_xxxxxx"

.mcp.json に記述する場合は "type": "http" を使い、トークンは環境変数経由で渡すとコミット漏れを防げます:

{
  "mcpServers": {
    "nolto": {
      "type": "http",
      "url": "https://nolto.app/mcp",
      "headers": { "Authorization": "Bearer ${NOLTO_MCP_TOKEN}" }
    }
  }
}

⚠️

Personal API Token はリソースに紐づかず mcp:read と mcp:write の両スコープを持ちます。パスワードと同様に扱い、不要になったらすぐに設定 > API トークンで失効（revoke）してください。 CI やコンテナでは、ソースコードにトークンを直書きせずシークレットマネージャーに保管してください。

代替: OAuth + SSH ポートフォワード

ローカル端末でポートを転送しておき、リモート側でコールバックを受け取る方法です。

# ローカル端末（リモート 33418 → ローカル 33418）
ssh -L 33418:localhost:33418 user@remote-host
# リモート側（SSH セッション内）
claude mcp add --transport http nolto https://nolto.app/mcp --callback-port 33418

認可 URL をローカルのブラウザで開いて承認すると、フォワードされたポートでコールバックが受領されます。

利用可能なツール

ツール	スコープ	説明
`list_projects`	`mcp:read`	参加プロジェクト一覧
`register_project`	`mcp:write`	新規プロジェクト作成
`set_default_project`	`mcp:write`	デフォルトプロジェクトを設定
`list_plans`	`mcp:read`	プラン一覧（ステータスフィルタ可）
`get_plan`	`mcp:read`	プラン詳細
`register_plan`	`mcp:write`	プラン登録（raw markdown）
`register_structured_plan`	`mcp:write`	構築済み StructuredPlan を直接登録（haiku 抽出をスキップ）
`update_plan_status`	`mcp:write`	プランのステータス変更
`update_phase_status`	`mcp:write`	フェーズのステータス変更
`record_phase_test_result`	`mcp:write`	フェーズのテスト結果を記録
`record_plan_review`	`mcp:write`	プランの最終レビュー（GO / NO-GO）を記録
`upload_plan_document`	`mcp:write`	プラン/フェーズに成果物ドキュメントを添付

各ツールの詳細は MCP ツールリファレンスを参照してください。

トラブルシューティング

`401 Unauthorized` が返る

OAuth Refresh Token の期限（30日）が切れている場合は、claude mcp add または codex mcp login で再認証してください。
ヘッドレス環境で OAuth コールバックが失敗する場合は、上の「ヘッドレス / リモート環境」セクションを参照し、Personal API Token または SSH ポートフォワードを使ってください。

`429 Too Many Requests` が返る

MCP エンドポイントには ユーザーあたり 60 リクエスト/分 のレート制限があります。Retry-After ヘッダーの秒数を待ってからリトライしてください。