ClaudeにWorkOS MCPをつないで認証基盤の設定を任せる手順

WorkOS MCPは、WorkOSのダッシュボードで行う作業をAIエージェントから実行するためのリモートMCPサーバーです。接続先はhttps://mcp.workos.com/mcpの1本で、Claudeに繋ぐと組織・SSO接続・ユーザー・ブランディングなどの確認と変更を、自然文の依頼で進められます。

認証基盤の設定は、間違えるとログインできなくなる領域です。この記事は接続手順だけでなく、Claudeが何を触れて何を触れないか、本番環境と書き込みをどう止めるかまで扱います。

WorkOS MCPでClaudeに任せられる作業

WorkOS MCPは、ダッシュボードと同じデータを、WorkOS APIの呼び出しを通して読み書きします。Claudeのコネクタ一覧に載るWorkOSのページは、扱える対象を次のように並べています。

• 組織、ユーザー、メンバーシップ
• SSO接続
• Directory Syncのディレクトリとユーザー
• ロール・権限・グループ(RBAC)
• 監査ログとイベント
• AuthKitのアプリケーション、ドメイン、Webhook

書き込みも対象で、組織やユーザーの作成・更新、接続の設定といった管理操作に使えます。操作は300以上あるとされています。数が多いので、Claudeが使うツールは4つだけです。

読み取りと書き込みが別のツールに分かれている点は、後半の権限設定で効いてきます。

接続の前に確認すること

接続前に決めておくことは3つあります。

1. WorkOSアカウント: 接続はOAuthで、WorkOS Connectを使った同意画面でサインインして承認します。共有のAPIキーは使いません
2. 自分のロール: エージェントは自分のダッシュボードロールをそのまま引き継ぎます。読み取り専用ロールなら、Claudeも変更はできません
3. チームのMCP設定: 管理者がMCPを無効にしていると、認証が通っても使えません。詳細は後述の管理設定の節にあります

コネクタ一覧のWorkOSのページには、サインインが必須と記載されています。

Claude CodeでWorkOS MCPを使う

Claude Codeでは、HTTPトランスポートでサーバーを追加します。

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

実行後にブラウザでWorkOSの同意画面が開くので、サインインして承認すると接続が完了します。Claude Codeの中では/mcpで接続状態の確認や再サインインができます。

設定の保存先を決めたい場合は、--scopeを付けます。省略時はローカルスコープで、追加したプロジェクトだけで有効になり、他の人には共有されません。

WorkOSのサーバーはあなたのアカウントとして動くので、--scope projectでチームに配るのは避けたほうが無難です。.mcp.jsonに載るのは接続先のURLだけでも、全員が自分のロールでサインインする構成になり、権限の異なる人が同じ設定を共有することになります。アカウント単位の接続は、localかuserで個人ごとに持つ形が噛み合います。

接続できたかどうかは、コマンドでも確かめられます。

claude mcp list
claude mcp get workos

claude mcp listは各サーバーの状態を✔ Connectedや! Needs authenticationのように表示します。Needs authenticationのままなら、/mcpからサインインをやり直します。

Claude Desktopから接続する

Claude Desktopでは、カスタムコネクタとして追加します。WorkOSのドキュメントにある手順は次のとおりです。

Anthropic認証済みのコネクタとしてもWorkOSは掲載されていて、コネクタ一覧のページの「Add to Claude」から追加する経路もあります。コネクタ全般の仕組みはClaudeのコネクタとはに整理しています。

権限の仕組み: Claudeは「あなた」として動く

WorkOS MCPで最も押さえたい点は、エージェントに独自の権限が無いことです。

ロールの引き継ぎ

接続すると、エージェントはあなたのダッシュボードアカウントとして認証され、ロールと権限をそのまま持ちます。管理者権限のないメンバーは、エージェント経由でも管理者専用の操作はできません。

環境は1つずつ、既定はサンドボックス

エージェントは同時に1つの環境だけを扱い、既定ではサンドボックス環境で動きます。本番を触るのは、あなたが指示したときだけです。本番への切り替えで権限が広がることはなく、ダッシュボードで元から入れる環境にしか届きません。

破壊的な操作は確認が挟まる

組織・接続・ディレクトリの削除のような取り消せない操作は、最初の呼び出しでは実行されません。何が失われるかの説明がエージェントに返り、明示的に確認してから実行されます。曖昧な指示ひとつでデータが消えない作りです。

シークレットは読み返せない

APIキーやクライアントシークレットといった値は、エージェントに返る前に取り除かれます。会話の記録に漏れないための仕組みです。一方で、あなたが渡した値を設定する書き込みは可能です。既存のシークレットを読むことだけができません。

管理者がMCPを止める設定

チームの管理者は、ダッシュボードのチーム認証設定にある「WorkOS MCP」の節で、MCP利用を制限できます。設定は3つで、既定ではすべて有効です。

これらの設定を変えられるのは管理者だけです。接続は成功したのにWorkOSへのアクセスが無効のままなら、チーム管理者にこの節を見てもらうのが次の一手になります。

Claudeのコネクタ一覧のページにも、管理者がコネクタを無効にしたり読み取り専用に絞ったりできると書かれています。導入するチームでは、まずAllow write accessをオフにして読み取りから始める運用が組めます。

Claude側でも書き込みを止める設定

WorkOS側の制限とは別に、Claude Code側でもツール単位で制御できます。MCPツールの権限ルールはmcp__<サーバー名>__<ツール名>の形で、サーバーをworkosの名前で追加していれば、書き込みのmutateはmcp__workos__mutateで指定できます。

.claude/settings.jsonに次のように書くと、読み取りは通し、書き込みは毎回確認する構成になります。

{
  "permissions": {
    "allow": [
      "mcp__workos__query",
      "mcp__workos__list_operations",
      "mcp__workos__whoami"
    ],
    "ask": [
      "mcp__workos__mutate"
    ]
  }
}

mutateを完全に使わせたくない調査用のセッションでは、askの代わりにdenyへ入れます。denyに入れたツールはClaudeの文脈から取り除かれます。

CLAUDE.mdに運用ルールを書いておくと、依頼の出し方も揃います。たとえば次のような断片です。

## WorkOS MCPの扱い
- 最初に whoami で接続中のアカウントと環境を確認する
- 既定はサンドボックス。本番への操作は、依頼文に「本番」と明記されたときだけ
- 変更系の操作は、実行前に対象のIDと変更内容を一覧で示して承認を待つ
- シークレットは読めない前提で、値の再取得を試みない

WorkOS側の確認(破壊的操作の事前確認)とClaude側の承認(ask)は別の層です。二重に確認が入るので、頻繁に使うならaskは書き込みのうち影響が大きいものに絞る、といった調整を後から入れる流れになります。

依頼文の例

WorkOSのドキュメントは、次のような依頼を例に挙げています。以下はその例示で、Claudeが実際に返す結果ではありません。

読み取り中心の依頼から始めるなら、設定の棚卸しと不審なサインインの確認が合います。どちらも変更を伴わないので、askに入れたmutateが一度も呼ばれないまま終わります。

できないこと

ダッシュボードの機能のうち、MCP経由では意図的に使えないものがあります。

• ユーザーのなりすまし(impersonation): ダッシュボードの機能はエージェントに公開されません。なりすまし中のセッションでの変更も遮断されます。エージェントは常にあなた自身として動きます
• 機微な操作: MCPのアクセス設定そのものの変更、APIキー・OAuthクライアントシークレット・署名証明書の発行やローテーション、WorkOSチームの削除はできません
• 複数チームの横断: エージェントは認証したチームの範囲に閉じます。別チームのリソースは読めません

つまり、Claudeに任せる範囲は日常の設定変更と調査です。認証情報の発行は人が行う作業として残ります。APIキーの作り直しを依頼してもClaudeはできないので、手順をダッシュボードで進める前提で組むことになります。

接続できないときの切り分け

接続まわりの不具合は、次の順で見ると原因が絞れます。

同名のサーバーを別のスコープに別のURLで登録していると、Claude Codeが警告を出します。OAuthのサインインはエンドポイントごとに保存されるため、プロジェクトによって別の定義が読み込まれると、片方でサインインしても他方では改めてサインインが必要です。WorkOSを試すときは、定義を1か所に絞っておくと混乱しません。

プラグイン以外のMCP追加を管理設定が止めている環境では、claude mcp add自体が失敗します。その場合の見分け方はclaude mcp addが失敗する原因にあります。

他の認証基盤MCPとの違い

同じ認証領域では、Auth0にもMCPサーバーがあります。手順と設定の違いはAuth0 MCPサーバーの設定ガイドで扱っています。WorkOS MCPの特徴は、接続がOAuthの1本で、操作をqueryとmutateに集約し、ロールの引き継ぎ・環境の分離・管理者による書き込み制限が最初から揃っている点です。

リモートMCPを自分たちのシステムに向けて立てる側の話は、Coworkカスタムコネクタの自作ガイドが参考になります。なお、WorkOSには自作のMCPサーバーをOAuthで守るためのAuthKit for MCPが別にあり、今回の管理用サーバーとは用途が違います。

まとめ

WorkOS MCPは、ClaudeにダッシュボードのAPI操作を任せる入口です。接続はclaude mcp add --transport http workos https://mcp.workos.com/mcpか、Claude Desktopのカスタムコネクタで、どちらもOAuthの同意で終わります。

任せ方の肝は、権限が自分のロールと同じで、シークレットの発行や管理設定の変更は最初から範囲外という点です。まずAllow write accessをオフにして、query中心の調査と棚卸しで使い始めると、設定ミスのリスクを抱えずに効果を確かめられます。書き込みを解禁する段階で、mcp__workos__mutateをaskに入れておくのが次の一手です。