mcp-server-agentops

AgentOps API MCP 服务

一个 MCP（模型协调协议）服务，允许大模型 Agent 与 AgentOps API 交互以访问追踪数据。

概述

此 MCP 服务为 Agent 提供以下工具：

• 列出其 AgentOps 项目中的近期追踪记录
• 获取特定追踪记录的详细信息

该服务负责处理身份验证并与 AgentOps API 通信，让 Agent 能够轻松访问追踪数据。

身份验证流程

该服务采用安全的两步身份验证流程：

1. Agent 在每次请求中提供其 AgentOps API 密钥
2. 服务将此 API 密钥交换为 AgentOps API 提供的 JWT 令牌
3. 服务使用此 JWT 令牌向 AgentOps API 发送经过身份验证的请求
4. 所有响应均以原始形式传回 Agent

这样可确保 API 密钥不会在请求之间存储，并且每个请求都通过 JWT 令牌安全地进行身份验证。

可用工具

list_traces

列出 Agent 项目中最新的追踪记录。

参数：

• AGENTOPS_API_KEY（必填）：Agent 的 AgentOps API 密钥
• limit（可选）：要返回的追踪记录的最大数量（默认值：5）
• AGENTOPS_API_URL（可选）：用于非生产环境的自定义 API URL

响应：

• 追踪记录列表，包含追踪 ID、跨度数量、开始／结束时间
• 数据库中的追踪记录总数
• 按创建时间戳排序的追踪记录（最新的在前）

trace_detail

获取特定追踪记录的详细信息。

参数：

• AGENTOPS_API_KEY（必填）：Agent 的 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。Agent 可以针对每个请求覆盖此 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")

架构

代码分为三个主要组件：

1. 客户端（client.py）：负责与 AgentOps API 通信，包括身份验证
2. 工具（tools.py）：定义 Agent 可用的工具并处理工具请求
3. 服务（server.py）：实现供 Agent 交互的 MCP 服务

每个请求均为无状态，不会在请求之间存储用户数据，并且 API 的原始响应会直接返回给 Agent。

Docker

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

后续增强

• 增加其他 AgentOps API 工具（指标、跨度等）
• 支持筛选和搜索追踪记录
• 批量操作以提升性能
• 在短时间内缓存 JWT 令牌