@invariance/mcp

一个将 AI 编码代理连接到 Invariance 可观测性平台的 MCP（模型上下文协议）服务器。它使 Claude Desktop、Cursor 和 Claude Code 等工具能够直接访问您的运行、节点、监控、信号、发现、审查等内容。

MCP 是一种开放协议，允许 AI 助手使用外部工具和数据源。此服务器为 Invariance 实现了该协议，因此您的 AI 助手无需离开对话即可查询可观测性数据、调查问题并分析代理行为。

安装

npm install -g @invariance/mcp

或者直接使用 npx 运行（推荐用于 MCP 客户端配置）：

npx @invariance/mcp

Related MCP server: Claude Code Starter Kit MCP

设置

环境变量

在 app.invariance.ai/settings/api-keys 获取您的 API 密钥。

Claude Desktop

添加到您的 Claude Desktop 配置中（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "invariance": {
      "command": "npx",
      "args": ["-y", "@invariance/mcp"],
      "env": {
        "INVARIANCE_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

添加到您的 Claude Code 配置中（.claude/settings.json 或 ~/.claude/settings.json）：

{
  "mcpServers": {
    "invariance": {
      "command": "npx",
      "args": ["-y", "@invariance/mcp"],
      "env": {
        "INVARIANCE_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor

添加到您的 Cursor MCP 设置中（.cursor/mcp.json）：

{
  "mcpServers": {
    "invariance": {
      "command": "npx",
      "args": ["-y", "@invariance/mcp"],
      "env": {
        "INVARIANCE_API_KEY": "your-api-key"
      }
    }
  }
}

可用工具

该服务器公开了 37 个工具，涵盖了完整的 Invariance API。名称遵循 invariance_<资源>_<操作>。

运行 (invariance_run_*) start, get, list, finish, fail, verify, metrics

节点 (invariance_node_*) write, list

监控 (invariance_monitor_*) create, list, get, update, pause, resume, evaluate, executions, findings

信号 (invariance_signal_*) emit, list, get, acknowledge, resolve

发现 (invariance_finding_*) list, get, update

审查 (invariance_review_*) list, get, claim, unclaim, resolve

代理 (invariance_agent_*) me, set_key

洞察 invariance_narrative_get（LLM 合成的运行摘要），invariance_ask（基于您的知识库 + 运行的轮次问答），invariance_kb_pages_list，invariance_kb_page_get

对于复杂的对象参数（监控主体、信号数据、节点输入/输出、运行元数据），工具接受 JSON 编码的字符串，服务器会在分发到 API 之前对其进行解析。

旧版工具别名

保留了早期版本的 6 个原始工具名称作为别名，以便现有的客户端配置可以继续工作：invariance_create_run, invariance_get_run, invariance_list_runs, invariance_write_node, invariance_list_nodes, invariance_verify_run。

HTTP 传输

要通过可流式 HTTP 而不是 stdio 运行服务器：

INVARIANCE_API_KEY=your-api-key INVARIANCE_MCP_TRANSPORT=http INVARIANCE_MCP_PORT=3000 npx @invariance/mcp

服务器在 http://127.0.0.1:3000/mcp 公开了一个可流式 HTTP 端点，并在 http://127.0.0.1:3000/health 提供健康检查。

支持 HTTP 传输的 MCP 客户端可以使用 /mcp 端点 URL 进行连接，而无需生成子进程。

故障排除

"INVARIANCE_API_KEY environment variable is required"

确保您已在 MCP 客户端配置中设置了 INVARIANCE_API_KEY 环境变量。请参阅上面的设置指南。

服务器未出现在您的 MCP 客户端中

1. 验证客户端的配置文件路径是否正确

2. 编辑配置后重启客户端

3. 检查 npx @invariance/mcp 在您的终端中运行是否没有错误

身份验证错误

验证您的 API 密钥在 app.invariance.ai/settings/api-keys 是否有效。

连接超时

如果使用自定义的 INVARIANCE_BASE_URL，请验证该 URL 是否可访问。

贡献

请参阅 CONTRIBUTING.md。

许可证

MIT