MCP Reference

The Invarium MCP server connects your IDE directly to the Invarium behavioral QA platform. It exposes 19 tools for registering agents, generating tests, executing test runs, and reviewing results — all through the Model Context Protocol.

Any MCP-compatible client works: Claude Desktop, Cursor, Claude Code, Windsurf, or a custom integration.

Key Takeaways

✓Server URL: https://mcp.invarium.dev/mcp
✓Authentication via Bearer token (inv_xxxxx) in the Authorization header
✓19 tools organized into three groups: Connection, Agents, and Testing
✓Stateless HTTP transport -- no session state between tool calls

Server Configuration

Configure the Invarium MCP server in your client’s MCP settings. The server URL is https://mcp.invarium.dev/mcp and authentication uses a Bearer token passed via the INVARIUM_API_KEY environment variable.

{
  "mcpServers": {
    "invarium": {
      "url": "https://mcp.invarium.dev/mcp",
      "env": {
        "INVARIUM_API_KEY": "inv_your_key_here"
      }
    }
  }
}

Get your API key from the Invarium dashboard under API Keys in the sidebar. Keys are scoped to a workspace — all agents and test runs created with a key belong to that workspace.

For full installation instructions including client-specific configuration for Claude Desktop, Cursor, and Claude Code, see Installation and Setup.

Tool Inventory

All 19 tools are listed below, organized by function. Each tool page includes parameters, response format, examples, and error handling.

Connection

Tools for verifying connectivity, checking plan usage, and viewing workspace status.

invarium_connect

Verify your API key and test the connection to the Invarium platform.

↗

invarium_usage

Show current plan usage and remaining limits for agents, test generations, and simulations.

↗

invarium_dashboard

Show the workspace dashboard overview with fleet health, pass rates, and recent runs.

↗

invarium_get_workflow

Retrieve the QA workflow guide for a specific phase to understand next steps.

↗

Agents

Tools for registering agents via blueprints, managing agent records, and reviewing audits.

invarium_prepare_blueprint

Validate a blueprint and run a local static audit before uploading.

↗

invarium_upload_blueprint

Upload an agent blueprint to the Invarium platform.

↗

invarium_get_agent

Get details for a specific agent including AQS score and audit status.

↗

invarium_list_agents

List all agents registered in your workspace.

↗

invarium_delete_agent

Permanently delete an agent and all associated data.

↗

invarium_get_audit

Retrieve the server-side audit results for an agent.

↗

Testing

Tools for generating test cases, managing scenarios, executing test runs, and syncing results.

invarium_setup_tracing

Install the behavioral trace library to your project for capturing agent test execution data.

↗

invarium_generate_tests

Generate behavioral test cases for an agent based on its blueprint.

↗

invarium_get_tests

Retrieve generated test cases and check generation status.

↗

invarium_sync_results

Sync test execution results from your IDE to the dashboard.

↗

invarium_list_test_runs

List test runs for an agent with status, pass rate, and timestamps.

↗

invarium_get_test_run

Get detailed results for a specific test run.

↗

invarium_list_scenarios

List test scenarios for an agent.

↗

invarium_create_scenario

Manually create a test scenario with custom parameters.

↗

invarium_manage_scenario

Update, delete, or toggle the status of a test scenario.

↗

Authentication

All MCP tools require a valid API key. The key is passed as a Bearer token in the Authorization header. When using an MCP client, set the INVARIUM_API_KEY environment variable in your server configuration and the client handles the header automatically.

API keys follow the format inv_ followed by an alphanumeric string. Each key is scoped to a single workspace.

To create or rotate keys:

Open the Invarium dashboard
Navigate to API Keys in the sidebar
Click Create Key or revoke an existing key and create a new one
Copy the key and update your MCP configuration

MCP Resources

The Invarium MCP server exposes four read-only resources that your MCP client can access:

Resource	URI	Description
Agent Blueprint Template	`invarium://templates/agent-blueprint`	JSON template with all supported blueprint fields. Use this to scaffold a new blueprint from scratch.
Blueprint Prompt	`invarium://templates/blueprint-prompt`	A natural-language prompt for generating a blueprint from your codebase. Give this to an LLM to analyze your agent code and produce a blueprint.
Trace Library	`invarium://templates/trace-library`	Python tracing library (`invarium_trace.py`) for capturing behavioral traces during test execution. Auto-patches OpenAI, Anthropic, Google Gemini, and LangChain SDKs.
Trace Prompt	`invarium://templates/trace-prompt`	Step-by-step guide for running behavioral test cases with tracing enabled and streaming results to the dashboard.

These resources are always available once the MCP server is connected.

Typical Workflow

The tools follow a structured workflow across five phases:

Connect — Call invarium_connect to verify your API key and connection.
Register — Use invarium_prepare_blueprint to validate your agent blueprint locally, then invarium_upload_blueprint to push it to the platform.
Generate — Call invarium_generate_tests to create behavioral test cases, then invarium_get_tests to retrieve them.
Execute — Run tests with the trace library, then use invarium_sync_results to stream results to the dashboard.
Analyze — Use invarium_dashboard, invarium_get_test_run, and invarium_get_agent to review results, AQS scores, and failure patterns.

For a complete walkthrough, see Quick Start.

Error Handling

All tools return plain text error messages with the cause and a suggested fix. For a complete reference of error codes and debugging strategies, see Error Codes.

Was this page helpful?

invarium_connect