Clerk MCPサーバーの使い方 — Claude Codeとclaude.aiへの接続

Clerk MCPサーバーとは

Clerk MCPサーバーは、Clerkが提供するリモートMCP(Model Context Protocol)サーバーです。Claude・Cursor・GitHub CopilotなどのAIエージェントに、Clerkの実装パターンとSDKスニペットを渡します。MCPは、AIエージェントが外部サービスのツールやデータへ接続するための標準プロトコルです。

Clerkのドキュメントは、Clerkで開発するすべての開発者にこのサーバーの利用を勧めています。渡される情報は次の3種類です。

データベースやインフラのMCPサーバーは、稼働中のシステムに接続して操作します。Clerk MCPサーバーが渡すのは、最新のSDKコード例と実装知識です。認証フローをゼロから書かせるのではなく、Clerkの実装パターンをそのままコードに反映させたいときに向いています。

ベータ版として提供されており、機能や挙動が今後変わる可能性があります。

自分のMCPサーバーを作る話とは別物

Clerkのドキュメントには、MCPに関するページがもう1系統あります。アプリ側にMCPサーバーを立て、ClerkのOAuth(認可の仕組み)で保護する方法を扱う「Build an MCP server」です。本記事の対象は、Clerkが用意した既存のサーバーにClaudeをつなぐ側で、両者は目的が違います。

検索結果にはどちらも「Clerk MCP」として出てきます。接続するだけでよいのか、自分のサービスをMCPで公開したいのかを先に決めると、読むページを間違えません。

Claude Codeに接続する

接続は2通りです。Clerk CLIでマシン上のAIクライアントをまとめて登録する方法と、Claude Codeの claude mcp add で個別に登録する方法です。

Clerk CLIで登録する

clerk mcp install

登録先を絞るときや、状況を確かめたいときは次のコマンドを使います。

# Claude Codeとcursorだけに登録
clerk mcp install --client claude --client cursor
 
# 検出した全クライアントに登録
clerk mcp install --all
 
# 登録済みのClerk MCPエントリを一覧表示
clerk mcp list
 
# 登録を削除
clerk mcp uninstall
 
# サーバーへの疎通を確認
clerk doctor

claude mcp addで登録する

Claude Codeのコマンドで、HTTPサーバーとして登録します。

claude mcp add clerk --transport http https://mcp.clerk.com/mcp

登録後、Claude Codeのセッション内で /mcp を実行すると接続状態を確かめられます。ターミナルから claude mcp list を実行すると、サーバーごとに ✔ Connected・! Needs authentication・✘ Failed to connect のいずれかが並びます。

実行すると何が書き込まれるか

claude mcp add は設定を書き込むコマンドで、接続できるかどうかは別に確かめます。v2.1.289でプロジェクトスコープとローカルスコープの両方を実行すると、次のように書き込まれます。

claude mcp add clerk --transport http --scope project https://mcp.clerk.com/mcp

Added HTTP MCP server clerk with URL: https://mcp.clerk.com/mcp to project config
File modified: /path/to/project/.mcp.json

作られた .mcp.json の中身は次のとおりです。

{
  "mcpServers": {
    "clerk": {
      "type": "http",
      "url": "https://mcp.clerk.com/mcp"
    }
  }
}

--scope project を付けずに登録すると、メッセージの末尾が to local config になります。書き込み先はリポジトリ内のファイルではなく、ホームの ~/.claude.json です。

Added HTTP MCP server clerk2 with URL: https://mcp.clerk.com/mcp to local config
File modified: ~/.claude.json [project: /path/to/project]

~/.claude.json では、プロジェクトのパスをキーにした mcpServers の下に、同じ type と url が入ります。ローカルスコープのサーバーが他のプロジェクトに現れないのは、このためです。

claude.aiに接続する

claude.aiのWeb版・デスクトップ版でも、同じサーバーに接続できます。

画面の案内には食い違いがあります。Clerkのドキュメントは「Settings → Integrations → Add more」と書き、Claude Codeのドキュメントはconnectorの追加先として claude.ai/customize/connectors を挙げています。Integrationsが見つからないときは、後者のURLから追加する手があります。TeamプランとEnterpriseプランでは、追加できるのは管理者だけです。

claude.ai側の登録がClaude Codeに届く条件

claude.aiで追加したMCPサーバーはconnectorと呼ばれ、claude.aiのアカウントでログインしたClaude Codeには自動で現れます。反映されない条件は、Claude Codeのドキュメントに次のとおり並んでいます。

• ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、apiKeyHelper のいずれかが有効
• Amazon BedrockなどのサードパーティプロバイダーまたはAnthropicプロファイルが有効
• claude setup-token で作った CLAUDE_CODE_OAUTH_TOKEN を使っている

/mcp にconnectorが出ないときは、/status で現在の認証方式を見ます。上のどれかが有効なら、Claude Codeには claude mcp add か clerk mcp install で直接登録します。

同じURLをclaude.aiとClaude Codeの両方に登録した場合は、Claude Codeに追加した側が優先されます。/mcp ではconnector側が「hidden」と表示され、重複を消す方法も案内されます。

Claude Desktop・他クライアントに接続する

Claude Desktopでは設定 → Developer → Edit Configから claude_desktop_config.json を開き、次の設定を追加してアプリを再起動します。

{
  "mcpServers": {
    "clerk": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.clerk.com/mcp"]
    }
  }
}

この設定は mcp-remote を経由してリモートURLへつなぐ形です。Claude Codeの --transport http では、URLを直接指定します。

Clerkのドキュメントには、Codex・Cursor・VSCode・Windsurf・Zed・fxの手順も載っています。それ以外のクライアントでは、エンドポイント https://mcp.clerk.com/mcp をStreamable HTTPで指定します。

使えるツールとスニペットバンドル

ツールは2つです。

接続後は、次のような質問でコード例を呼び出せます。

• 「ClerkのuseUserフックの使い方を教えて」
• 「Clerk OrganizationsでB2B SaaSを構築する手順を見せて」
• 「Clerkでウェイトリストを実装する方法は」
• 「Next.jsでClerkを使ってルートを保護する最善の方法は」

まとまった実装が必要なときは、複数機能をまとめたバンドルを指定できます。

実装フローの例 — B2B SaaSの認証を組み立てる

Next.jsアプリに組織単位のログインを追加する場面を考えます。Clerkのドキュメントは、このサーバーの役割をAIエージェントに最新のコード例を渡すことと説明しています。

接続した状態では、依頼文にバンドル名を含めておくと、取得する範囲を指定できます。

Clerk Organizationsを使ったB2B SaaSのログイン画面を作って。
Clerk MCPサーバーの b2b-saas バンドルを取得してから実装して。

b2b-saas には、Organizations・課金・ロールベースアクセスまでが含まれます。個別の機能を都度調べ直す手間が減ります。

既存のClerk実装を拡張するときも同じです。「今のサインインフローにウェイトリストを追加したい。waitlist バンドルを使って」と伝えれば、そのスニペットを起点にした提案を依頼できます。ドキュメントを開いてAPIの引数を確かめる作業を、チャット内の質問に置き換えられます。

どのスコープに登録するか

claude mcp add のスコープは3つで、Clerk MCPサーバーもこの仕組みに従います。状況から選ぶ早見表です。

チームで共有するときは、--scope project で .mcp.json に書き出してコミットします。

claude mcp add clerk --transport http --scope project https://mcp.clerk.com/mcp

.mcp.json のサーバーは、チームメンバーが初めてそのリポジトリでClaude Codeを開いたときに承認を求められます。承認前の claude mcp list には、⏸ Pending approval (run claude to approve) と出ます。承認を選び直したいときは、claude mcp reset-project-choices で選択をリセットできます。

v2.1.196以降は、信頼していないフォルダーでは、リポジトリにコミットされた .claude/settings.json の承認設定が無視されます。クローンしただけのリポジトリが、自分でサーバーを承認することはできません。

他のMCPサーバーとの併用

MySQLやFly.ioのMCPサーバーは、稼働中のデータベースやインフラを操作対象にします。Clerk MCPサーバーのツールは、公式の一覧ではスニペットの取得と一覧の2つだけです。同じプロジェクトに併用できるので、Clerk MCPサーバーで認証コードを組み立て、DB系のサーバーでスキーマを確かめる、という分担もできます。

MySQL MCPサーバーやFly.ioのMCPサーバーは、運用中のインフラを直接操作する側の例です。claude mcp add の構文やスコープの詳細は、Claude Code MCP設定ガイドで扱っています。

よくあるつまずき

Internal server errorが出て接続できない

ネットワークまたはトランスポートの問題であることが多いと案内されています。MCPサーバーを一度切断して再接続し、使っているクライアントがStreamable HTTPトランスポートに対応しているかを見ます。

SSE接続を試して失敗する

Clerk MCPサーバーはServer-Sent Events(SSE)に対応していません。対応するのはStreamable HTTPのみで、エンドポイントは https://mcp.clerk.com/mcp です。SSE専用の手順をコピーした場合は、HTTPトランスポート向けに書き換えます。Claude Codeでは --transport http を指定します。

/mcp にClerkが出ない、または claude mcp list で失敗と出る

claude mcp list が ✘ Failed to connect を表示するときは、接続に失敗した理由が同じ行に添えられます(v2.1.219以降)。HTTPステータスやサーバーが返したエラー文が手がかりです。⏸ Pending approval なら接続の失敗ではなく、承認待ちです。

ツールの入出力やバンドルの構成が変わった

ベータ版のため、入出力やバンドルの構成は今後変わる可能性があります。既存のプロンプトが動かなくなったときは、clerk mcp list や /mcp でサーバーの接続状態を確かめます。

まとめ

自分のプロジェクトで試すだけなら claude mcp add の既定(local)で足ります。チームで同じ設定を使うなら --scope project と承認手順まで、複数クライアントに入れるなら clerk mcp install を選びます。

claude.aiのconnectorは、APIキーなどclaude.aiログイン以外の認証でClaude Codeを使っていると届きません。その場合は、Claude Code側に直接登録します。