@invariance/mcp

An MCP (Model Context Protocol) server that connects AI coding agents to the Invariance observability platform. It gives tools like Claude Desktop, Cursor, and Claude Code direct access to your traces, monitors, signals, and more.

MCP is an open protocol that lets AI assistants use external tools and data sources. This server implements it for Invariance, so your AI assistant can query observability data, investigate issues, and analyze agent behavior without leaving the conversation.

Install

npm install -g @invariance/mcp

Or run directly with npx (recommended for MCP client configs):

npx @invariance/mcp

Setup

Environment variables

Variable	Required	Default	Description
`INVARIANCE_API_KEY`	Yes	—	Your Invariance API key
`INVARIANCE_BASE_URL`	No	`https://api.invariance.ai`	API base URL
`INVARIANCE_MCP_TRANSPORT`	No	`stdio`	Transport mode: `stdio` or `sse`
`INVARIANCE_MCP_PORT`	No	`3000`	Port for SSE/HTTP transport
`INVARIANCE_TIMEOUT`	No	`30000`	Request timeout in milliseconds

Get your API key at app.invariance.ai/settings/api-keys.

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Claude Code

Add to your Claude Code config (.claude/settings.json or ~/.claude/settings.json):

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

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

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

Available tools

Tool	Description
`whoami`	Get information about the authenticated Invariance user and organization
`list_traces`	List recent traces from Invariance with optional filtering
`get_trace`	Get detailed information about a specific trace by ID
`query_invariance`	Query Invariance with a natural language prompt to analyze traces, monitors, and signals
`list_monitors`	List configured monitors in Invariance
`run_monitor`	Trigger a monitor run and return the results
`list_signals`	List signals detected by Invariance monitors
`get_session`	Get detailed information about an agent session
`search_docs`	Search Invariance documentation for a topic
`list_datasets`	List available evaluation datasets
`list_evals`	List evaluation runs with optional dataset filtering
`create_monitor`	Create a new monitor in Invariance to track agent behavior
`create_dataset`	Create a new evaluation dataset in Invariance
`get_monitor`	Get detailed information about a specific monitor including recent runs
`get_eval`	Get detailed results of an evaluation run

Available prompts

Prompt	Description
`troubleshooting`	Help troubleshoot an issue with an Invariance-monitored agent
`monitor-investigation`	Investigate why a monitor triggered or is failing
`trace-analysis`	Analyze a trace to identify issues, bottlenecks, or anomalies

Available resources

URI	Description
`invariance://docs/{topic}`	Invariance documentation by topic

Topics: getting-started, authentication, traces, monitors, signals, queries, datasets, evals

SSE/HTTP transport

To run the server in SSE/HTTP mode instead of stdio:

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

The server exposes a Streamable HTTP endpoint at http://127.0.0.1:3000/mcp and a health check at http://127.0.0.1:3000/health.

MCP clients that support HTTP transport can connect using the /mcp endpoint URL instead of spawning a subprocess.

Troubleshooting

"INVARIANCE_API_KEY environment variable is required"

Make sure you've set the INVARIANCE_API_KEY environment variable in your MCP client configuration. See the setup guides above.

Server not appearing in your MCP client

Verify the config file path is correct for your client
Restart the client after editing the config
Check that npx @invariance/mcp runs without errors in your terminal

Authentication errors

Verify your API key is valid at app.invariance.ai/settings/api-keys.

Connection timeouts

If using a custom INVARIANCE_BASE_URL, verify the URL is reachable.

Contributing

See CONTRIBUTING.md.

License

MIT

Invariance MCP