mcp-api-key-auth

用途

mcp-api-key-auth 用于让外部 MCP 客户端（如 Claude Code、Cursor 等）使用独立的 API Key 对股票数据服务进行认证，并跟踪每个工具的使用情况（表名、记录数）以便监控。

适用场景包括：

用户需要创建或管理 MCP API Key
用户需要将外部 MCP 客户端配置为连接此服务
用户需要查看 MCP 工具使用统计（调用了哪些工具、查询了哪些表、多少条记录）
用户需要排查 MCP 认证错误（401、无效密钥、过期密钥）

架构

API Key 管理位于 HTTP 服务器（端口 8000），由 JWT 登录保护
MCP 协议位于 MCP 服务器（端口 8001），由请求头中的 API Key 保护
使用跟踪记录存储在 ClickHouse 的 mcp_tool_usage_log 表中

使用方式

1) 创建 API Key

先登录获取 JWT token，再创建 API Key：

# Login
JWT=$(curl -s -X POST http://<host>:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"your@email.com","password":"yourpassword"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

# Create API key
curl -s -X POST http://<host>:8000/api/mcp-keys/create \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"key_name": "my-cursor-key", "expires_days": 90}'

响应中包含完整的 API Key（例如 sk-a1b2c3d4...）。请立即保存——它仅显示一次。

2) 配置 MCP 客户端

Claude Code / Claude Desktop

添加到 MCP 配置（claude_desktop_config.json 或项目 .mcp.json）：

{
  "mcpServers": {
    "stock-data": {
      "url": "http://<host>:8001/messages",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer sk-your-api-key-here"
      }
    }
  }
}

Cursor

在 Cursor 设置中添加 MCP server：

URL: http://<host>:8001/messages
Header: Authorization: Bearer sk-your-api-key-here

3) 验证连通性

# Should return tool list (not 401)
curl -s -X POST http://<host>:8001/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

4) 查看使用统计

# Usage history (paginated)
curl -s "http://<host>:8000/api/mcp-usage/history?page=1&page_size=20" \
  -H "Authorization: Bearer $JWT"

# Aggregated stats (last 30 days)
curl -s "http://<host>:8000/api/mcp-usage/stats?days=30" \
  -H "Authorization: Bearer $JWT"

5) 管理 API Key

# List all keys
curl -s http://<host>:8000/api/mcp-keys/list \
  -H "Authorization: Bearer $JWT"

# Revoke a key
curl -s -X POST http://<host>:8000/api/mcp-keys/revoke \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"key_id": "<key-id>"}'

关键端点

Endpoint	Method	Auth	Description
/api/mcp-keys/create	POST	JWT	Create new API key
/api/mcp-keys/list	GET	JWT	List user's API keys
/api/mcp-keys/revoke	POST	JWT	Revoke an API key
/api/mcp-usage/history	GET	JWT	Paginated usage history
/api/mcp-usage/stats	GET	JWT	Aggregated usage stats
/messages (MCP)	POST	API Key	MCP protocol endpoint

排查

401 "API key required"：MCP 调用缺少 Authorization 头
401 "Invalid or expired API key"：密钥被撤销或过期——创建新的密钥
initialize 可用但 tools/list 失败：initialize 不需要认证；tools/list 与 tools/call 需要
使用记录未显示：使用日志为即发即忘（fire-and-forget）；直接检查 ClickHouse 的 mcp_tool_usage_log 表

验证清单

API key 已创建并返回完整密钥（仅显示一次）
无 API key 时 tools/list 返回 401
有效 API key 时 tools/list 返回工具列表
tools/call 在 mcp_tool_usage_log 表中记录使用情况
已撤销的密钥在后续调用中返回 401
使用历史 API 返回正确数据
使用统计显示每日调用次数和热门工具