Claude CodeにConvex MCPサーバーをつないでバックエンドを書かせる

Convex MCPサーバーは、Claude Codeが稼働中のConvexデプロイメントを直接読み書きするための窓口です。テーブルのスキーマ、保存済みのデータ、デプロイ済み関数の仕様、実行ログを、Claude Codeが推測ではなく実物から取ってきます。起動コマンドはnpx -y convex@latest mcp startの1行で、Claude Codeなら公式プラグインを入れるだけで自動的に立ち上がります。

Convex MCPサーバーでClaude Codeは何を読み書きできるか

Convexは、バックエンドをTypeScriptの関数として書くサービスです。MCPサーバーはその開発用デプロイメントに対する操作を12個のツールとして公開します。ツールは役割ごとに5つに分かれます。

runOneoffQueryは読み取り専用で、データベースを書き換えられません。書き込みを伴うのはrunとenvSet、envRemoveの3つです。この区別は、後の権限設計でそのまま効いてきます。

バックエンドを書かせるときに効くのはtablesとfunctionSpecです。Claude Codeは新しい関数を書く前に既存のスキーマと関数の型を読めるので、存在しないフィールドを参照するコードが減ります。書いた関数をrunで呼び、失敗したらlogsで原因を読む、という反復も同じセッション内で回せます。

接続方法は2通り: プラグインか手動登録か

推奨される導入方法はプラグインです。Claude Codeでは次の1行です。

/plugin install convex@claude-plugins-official

プラグインはMCPサーバーに加えて、フック、スキル、専用サブエージェントを同梱します。公式マーケットプレイスの掲載ページは、中身を「bundled Convex skills、convex-expert subagent、runtime-error monitor、MCP access」と書いています。導入済みのプラグインを扱う手順はClaude Codeプラグイン完全ガイドにあります。

MCPサーバーだけが欲しいときは、claude mcp addで手動登録します。stdioサーバーなので、--の後ろにサーバーの起動コマンドを置きます。

claude mcp add --transport stdio convex -- \
  npx -y convex@latest mcp start

登録後は、セッション内の/mcpで接続状態とツール数を見られます。ターミナルからならclaude mcp listでConnectedかどうかを確かめます。JSONで登録したい場合の書式はclaude mcp add-jsonの手順に任せて、ここでは手動登録の注意点だけ押さえます。

• 手動でconvexと名付けると、ツール名はmcp__convex__statusの形になります
• プラグイン経由で入った場合は、ツール名にプラグイン名が含まれる別の形になります。権限ルールを書く前に/mcpでサーバーを選び、実際の名前を見てください
• 両方を有効にすると、同じ機能が二重に並びます。どちらか一方に決めます

最初の1回で何を頼むか

Convexのプロジェクトでclaudeを起動したら、まず現状を読ませます。設定ページに載っている依頼の例は次のとおりです。

• 「Convexのスキーマを評価して、改善案を出して」
• 「このアプリの公開エンドポイントは何か」
• 「my_convex_functionクエリを実行して」

この例でClaude Codeの内部で起きるのは、おおむね次の順です。statusでデプロイメントを選び、tablesでスキーマを読み、functionSpecで関数の公開範囲を調べます。実際の呼び出し順はモデルの判断で変わります。

何もない状態から始めるなら、空のディレクトリで次のように起動します。設定ページにはこの形が載っています。

claude "build me a todo app with Convex" \
  --permission-mode auto

Claude Codeがnpm create convex@latestとnpx convex dev --onceを実行します。非対話のシェルなのでログインは求められず、ローカルのバックエンドが自動で用意されます。

本番デプロイメントはなぜ読めないのか

Convex MCPサーバーは、初期状態で本番を守る作りです。本番では読み取り専用の操作しか許さず、個人情報(PII)を含みうるツールも止めます。

本番で障害を調べたいだけなら、--cautiously-allow-production-piiで足ります。データとログは読めて、書き込みと環境変数は閉じたままです。--dangerously-enable-production-deploymentsは、書き込みと環境変数まで開けます。名前にdangerouslyが付くとおり、本番のデータを変更できる状態になります。

本番の既定デプロイメントをMCPの接続先にする--prodは、--dangerously-enable-production-deploymentsとセットで使います。

Claude Code側でも絞る: 権限ルールとデプロイキー

MCPサーバー側のフラグと、Claude Code側の権限ルールは別の層です。二重に絞ると、設定ミスがあっても片方が止めます。

接続先を1つのデプロイメントに固定する

Convex MCPサーバーは、npx convex loginで得た全体の認証情報を使います。そのままだと、アカウントがアクセスできる全プロジェクトに手が届きます。1つのデプロイメントに限定するには、デプロイキーを生成して環境変数に渡します。

claude mcp add --transport stdio \
  --env CONVEX_DEPLOY_KEY="dev:happy-capybara-849|…" \
  convex -- npx -y convex@latest mcp start

この方法には制約があります。デプロイキーで起動すると、insightsツールが使えません。性能問題の調査が必要なら、キーなしの接続に切り替えます。--project-dirで対象プロジェクトを指定しても、Claude Codeがstatusの呼び出しで別のプロジェクトを指定する余地は残ります。境界を守る目的には使えません。

プレビュー環境を読ませたいチームには、デプロイキー以外の選択肢もあります。--preview-nameにプレビューデプロイメントの名前を渡すと、そのプレビューに接続します。--env-fileは、CONVEX_DEPLOYMENTなどを書いた別の環境ファイルを接続先の決定に使うフラグで、書式は.env.localと同じです。ブランチごとに環境ファイルを分けておけば、登録コマンドの引数だけで接続先を切り替えられます。

書き込み系のツールを権限ルールで拒否する

書き込みを伴うrun、envSet、envRemoveは、Claude Codeの設定でも拒否できます。MCPのツール名はmcp__<サーバー名>__<ツール名>の形です。手動登録でconvexと名付けた場合の例です。

{
  "permissions": {
    "deny": [
      "mcp__convex__envSet",
      "mcp__convex__envRemove"
    ],
    "ask": [
      "mcp__convex__run"
    ]
  }
}

runは開発デプロイメントでの動作確認に便利なので、拒否ではなく都度確認にしています。ルールの書式と/permissionsでの確認方法はClaude Codeの/permissionsコマンドで解説しています。

MCPサーバー側で閉じる方法もあります。--disable-toolsにツール名をカンマ区切りで渡します。

npx -y convex@latest mcp start \
  --disable-tools envSet,envRemove,run

無効にできるのはdata、envGet、envList、envRemove、envSet、functionSpec、insights、logs、run、runOneoffQuery、status、tablesの12個です。

CLAUDE.mdに運用規約を書いておく

権限ルールは「できるか」を決めます。「何を先にやるか」はCLAUDE.mdで伝えます。次は、Convexのプロジェクトに置く規約の一例です。

## Convex
- 関数を書く前に、MCPの`tables`と`functionSpec`でスキーマと既存関数を読む
- 変更後は`logs`で実行エラーを確認してから完了を報告する
- 本番デプロイメントには接続しない。環境変数は変更しない
- スキーマ変更は既存ドキュメントへの影響を説明してから行う

npx convex ai-files installを実行すると、Convexのガイドラインがconvex/_generated/ai/guidelines.mdと、CLAUDE.md内の管理セクションに入ります。プラグインを使わない場合も、この仕組みで規約を足せます。上の規約は、そのセクションとは別の自前の部分に書くと管理しやすくなります。

プラグインが足す3つの層

MCPサーバーはツールの層です。プラグインは、その上に3つを足します。

公式ページが挙げるスキルは次の6つです。

公式は、API名ではなく結果を伝えて頼むことを勧めています。「プロフィール画像をアップロードできるようにして」と頼めば、適切なスキルに振り分けられるという説明です。

つまずきやすい点

• フラグ名が2種類ある: 設定ページは--deployment-nameを、CLIリファレンスは--deploymentを載せています。CLIリファレンスはdev・prod・localといった参照も受け付けると書いています。手元のconvexのバージョンでnpx convex mcp start --helpを確認してから使ってください
• --prodは単独で使えない: 本番へ接続するフラグは、--dangerously-enable-production-deploymentsの指定を求めます
• insightsが消える: CONVEX_DEPLOY_KEYで起動すると、このツールは本番・非本番とも使えません
• ツールが見えない: /mcpでFailed to connectなら、claude mcp listの失敗理由を読みます。npxでサーバーを起動できているか、登録したコマンドを手元のシェルで直接実行して確かめます

MCPサーバーを自作したい場合は、mcp-server-devプラグインの解説が入口になります。MCP全般の仕組みと承認の考え方はClaude CodeのMCP実践ガイドにあります。

まとめ

Convex MCPサーバーの価値は、Claude Codeがスキーマ・関数・ログを実物から読める点にあります。プラグインで入れるのが最短ですが、サーバーだけを手動登録すれば、ツールの範囲を自分で選べます。本番には既定で触れないので、開く場合は--cautiously-allow-production-piiから試し、書き込みを開ける前にデプロイキーとClaude Code側の権限ルールで二重に絞るのが堅実です。