mcp-api

FusionAuth API MCP サーバーのプレビュー（fusionauth-mcp-api）

FusionAuth API 用 MCP サーバーのプレビューリリースです。 優れたgithub.com/harsha-iiiv/openapi-mcp-generatorを使用して構築されています。

⚠️ 本番環境では使用しないでください！

この MCP サーバーを使用するには、MCP クライアントに FusionAuth API キーを提供する必要があります。開発環境とテスト環境でのみ使用してください。機密情報が漏えいする可能性について、FusionAuth は責任を負いません。

前提条件

• 稼働中の FusionAuth インスタンス
• Node.js

設定

まず、FusionAuth インスタンスで権限を制限した API キーを設定します。API キーの作成およびAPI キーに適切な権限を設定する方法に関するドキュメントを参照してください。

次に、FusionAuth API MCP サーバーを使用するように MCP クライアントを設定します。

たとえば、Claude Desktop に追加するには、~/Library/Application Support/Claude/claude_desktop_config.jsonを編集し、以下のfusionauth-mcp-apiキーを含めます。

以前に MCP サーバーをインストールしたことがない場合、次のようになります。

{
  "mcpServers": {
      "fusionauth-mcp-api": {
      "command": "npx",
      "args": [
        "@fusionauth/mcp-api"
      ],
      "env": {
        "API_KEY_APIKEYAUTH": "<your fusionauth api key>",
        "API_BASE_URL": "http://localhost:9011",
        "USE_TOOLS": "retrieve,search"
      }
    }
  }
}

上記のUSE_TOOLS環境変数は、利用可能なツールを読み取り専用の操作に制限します。この変数を省略するとすべてのアクセスが許可されますが、約 200k トークンを処理できるモデルが必要です。

MCP サーバーをクライアントに追加する正確な方法については、お使いの MCP クライアントのドキュメントを参照してください。

プロンプトの例

• 「どのツールを利用できますか？」と尋ねると、FusionAuth API のすべてのツールが表示されます
• 「FusionAuth のアプリケーションはいくつありますか？」
• 「FusionAuth インスタンスにはユーザーが何人いますか？」
• 「メールアドレスが [email protected]、パスワードが 'password' のユーザーを追加して」（制限の緩いツールが必要です）

ツールの制限

デフォルトの MCP サーバーには、FusionAuth のすべての API エンドポイントに対応するツールがあります。その数は 300 を超えます！ ただし、ツール、説明、リクエスト、レスポンスを合わせると約 200k トークンになり、 多くの MCP クライアントのコンテキストウィンドウを超える場合があります。

上記のとおりUSE_TOOLS環境変数を設定することで、この MCP サーバーが利用可能にするツールを制限できます。

各ツールはプレフィックスで定義されています。デフォルトのプレフィックスは次のとおりです。

• create
• delete
• patch
• update
• retrieve
• search

また、別のプレフィックスを持つすべてのツールを含むotherツールバケットもあります。allツールバケットにはすべてのツールが含まれ、デフォルト値です。

たとえば、deleteまたはpatchメソッドを使用する必要がない場合は、次の設定でツールの一覧を 20% 削減できます。

USE_TOOLS="create,update,retrieve,search,other"

読み取り専用の操作のみを許可する場合は、次の設定を使用してください。

USE_TOOLS="retrieve,search"

これにより、ツールの一覧のサイズも 66% 削減されます。

MCP サーバーのセキュリティ保護

MCP サーバーを保護する方法は 3 つあります。機能上のニーズを満たしながら FusionAuth インスタンスへのアクセスを安全にするには、これらを組み合わせてください。細かさの度合いが粗いものから細かいものの順に、次のとおりです。

• 正しいインスタンスを指定します。このツールはプレビュー段階のため、ローカルの開発用インスタンスのみを指定することをおすすめします。
• 適切な種類のツールを有効にします。コンテキストウィンドウの使用量を減らせるだけでなく、LLM が実行できるリクエストの種類を制限することで、セキュリティを強化できます。たとえば、delete ツールのセットを有効にしなければ、LLM が FusionAuth の設定を削除して「支援」してくる心配はありません。
• API キーを厳格に制限します。これにより、ツールの選択を超えて、きめ細かく制御できます。MCP サーバーは API キーを使用して FusionAuth と通信します。適切な権限セットを選択することで、その API キーがテナント、アプリケーション、ユーザーに対してのみ操作できるように制限できます。

トラブルシューティング

MCP クライアントが実行しようとしている操作に対して、API キーに適切な権限があることを確認してください。

MCP クライアントのログを確認してください。ログの場所は、MCP クライアントやプラットフォームによって異なります。たとえば、macOS の Claude Desktop のログは $HOME/Library/Logs/Claude/mcp-server-fusionauth-api-server.log にあります。正確な場所については、クライアントのドキュメントを参照してください。

問題が MCP サーバーと MCP クライアントのどちらにあるかを調べるには、modelcontextprotocol inspector を使用してください：npx @modelcontextprotocol/inspector。USE_TOOLS 変数を変更したい場合、動的には変更できないため、コマンドラインで渡す必要があります。npx @modelcontextprotocol/inspector npx @fusionauth/mcp-api -e API_KEY_APIKEYAUTH=... -e USE_TOOLS=create

ローカルでのビルド

ローカルでビルドして実行することもできます。

git clone https://github.com/FusionAuth/fusionauth-mcp-api.git
cd fusionauth-mcp-api
cd packages/mcp-api
npm install
npm run build

# optional step to store config information in .env file
cp .env.example .env
# optionally edit .env to set API_BASE_URL and API_KEY_APIKEYAUTH

その後、上記の手順と同様に、FusionAuth API MCP サーバーを使用するように MCP クライアントを設定します。

たとえば、Claude Desktop に追加するには、~/Library/Application Support/Claude/claude_desktop_config.json を編集し、以下の fusionauth-mcp-api キーを追加します。以前に MCP サーバーをインストールしていない場合は、次のようになります。

{
  "mcpServers": {
    "fusionauth-mcp-api": {
      "command": "npm",
      "args": [
        "run",
        "--silent",
        "--prefix",
        "<path to local git repo>/fusionauth-mcp-api/packages/mcp-api",
        "start"
      ],
      "env": {
        "API_KEY_APIKEYAUTH": "<your fusionauth api key>",
        "API_BASE_URL": "http://localhost:9011",
        "USE_TOOLS": "retrieve,search"
      }
    }
  }
}

.env ファイルを設定している場合は、上記の env セクションを省略できます。

公開

bin/updatemcp.sh git commit git tag git push origin main --tags npm publish --access public --workspace=packages/mcp-api

フィードバック

機能リクエストやバグは、このリポジトリでお知らせください。

興味深いユースケースを共有したい場合や、機能の使い方について質問したい場合は、FusionAuth フォーラムに投稿してください。