mcp-server-agentops

AgentOps API MCP サーバー

LLM エージェントが AgentOps API と連携してトレースデータにアクセスできる MCP（Model Coordination Protocol）サーバーです。

概要

この MCP サーバーは、エージェントが以下を実行するためのツールを提供します。

• AgentOps プロジェクトの最近のトレースを一覧表示する
• 特定のトレースの詳細情報を取得する

サーバーが AgentOps API との認証と通信を処理するため、エージェントはトレースデータに簡単にアクセスできます。

認証フロー

サーバーは、安全な2段階の認証プロセスを使用します。

1. エージェントはリクエストごとに AgentOps API キーを提供します
2. サーバーはこの API キーを AgentOps API の JWT トークンと交換します
3. サーバーはこの JWT トークンを使用して、AgentOps API に認証済みリクエストを送信します
4. すべてのレスポンスは加工せず、そのままエージェントに返されます

これにより、API キーがリクエスト間で保存されず、各リクエストが JWT トークンで安全に認証されます。

利用可能なツール

list_traces

エージェントのプロジェクトから最新のトレースを一覧表示します。

パラメーター：

• AGENTOPS_API_KEY（必須）：エージェントの AgentOps API キー
• limit（任意）：返すトレースの最大数（デフォルト：5）
• AGENTOPS_API_URL（任意）：本番環境以外で使用するカスタム API URL

レスポンス：

• トレース ID、スパン数、開始時刻／終了時刻を含むトレースの一覧
• データベース内のトレース総数
• 作成タイムスタンプ順（新しい順）に並べられたトレース

trace_detail

特定のトレースの詳細情報を取得します。

パラメーター：

• AGENTOPS_API_KEY（必須）：エージェントの AgentOps API キー
• trace_id（必須）：詳細を取得するトレース ID（list_traces のレスポンスにある trace_id フィールドから取得）
• AGENTOPS_API_URL（任意）：本番環境以外で使用するカスタム API URL

レスポンス：

• トレースの詳細情報
• トレースに関連付けられたすべてのスパン
• メタデータ、タイミング情報など

使用方法

Claude Coder での使用（推奨）

この MCP サーバーは Claude Coder で動作するように設計されています。以下の手順に従って設定してください。

1. Claude Coder を設定する

   Claude Coder の設定ファイル（通常は ~/.config/claude-cli/config.yaml）に以下を追加します。

   mcp_servers:
     - name: agentops-api
       path: /ABSOLUTE/PATH/TO/mcp/agentops-api/bin/run-server
       description: "AgentOps API integration for accessing trace data"
   

   /ABSOLUTE/PATH/TO を、このリポジトリの実際のパスに置き換えてください。

2. Claude Coder で使用する

   # Run Claude with the AgentOps API MCP server enabled
   claude --mcp agentops-api
   
   # Or for a single command
   claude --mcp agentops-api "List my recent traces. My API key is xyz123"
   

3. Claude へのプロンプトに AgentOps API キーを含めます。

   Can you show me my recent traces? Find my agentops api key in my user .env file. 
   

単独で実行する

サーバーを直接実行する必要がある場合は、以下を実行します。

# Using the convenience script
./bin/run-server

# Or using Python directly
uv run -m mcp_server_agentops_api

デフォルトでは、サーバーは本番環境の AgentOps API（https://api.agentops.ai）を使用します。エージェントはリクエストごとにこの URL を変更できます。

利用可能なツール呼び出し

Claude を通じて MCP サーバーを使用する場合、以下のツールを利用できます。

# List recent traces
list_traces(AGENTOPS_API_KEY="your-api-key", limit=10)

# Get details for a specific trace
trace_detail(AGENTOPS_API_KEY="your-api-key", trace_id="148dac266d95c9dc0b5616320b8488c9")

# Using a custom API URL (e.g., for local development)
list_traces(AGENTOPS_API_KEY="your-api-key", AGENTOPS_API_URL="http://localhost:8000")

アーキテクチャ

コードは、次の3つの主要コンポーネントで構成されています。

1. クライアント（client.py）：認証を含む、AgentOps API との通信を処理します
2. ツール（tools.py）：エージェントが利用できるツールを定義し、ツールリクエストを処理します
3. サーバー（server.py）：エージェントが操作する MCP サーバーを実装します

各リクエストはステートレスで、リクエスト間でユーザーデータは保存されません。また、API の生レスポンスがそのままエージェントに返されます。

Docker

# Build and run the Docker container
docker build -t mcp-server-agentops-api .
docker run mcp-server-agentops-api

今後の拡張

• AgentOps API ツールの追加（メトリクス、スパンなど）
• トレースのフィルタリングと検索への対応
• パフォーマンス向上のためのバッチ操作
• JWT トークンの短期間のキャッシュ