`invarium_connect`

Verify your API key and connect to the Invarium platform. This is the first tool to call in any session.

When to Use

Call invarium_connect at the start of every session, or after changing your API key or MCP configuration. It confirms end-to-end connectivity — from your IDE through the MCP server to the Invarium backend — and sets up your local project directory.

After a successful connection, you can proceed to any other tool: register an agent, generate tests, or view your dashboard.

See Installation and Setup for configuring the MCP server in your IDE.

Parameters

This tool takes no parameters. Authentication is handled automatically via the INVARIUM_API_KEY environment variable in your MCP server configuration.

invarium_connect

Verify your API key and connect to the Invarium platform. Returns setup instructions for configuring your project.

Returns

Connection status, account info, and setup instructions for your IDE assistant to execute.

Example

"Connect to Invarium and verify my API key"

Response

On success, the tool returns your account info and setup instructions:

Connected to Invarium ✓
Account: you@example.com
Workspace: my-workspace

SETUP — Run these commands and create this file:

1. mkdir -p .invarium && grep -qxF '.invarium/' .gitignore 2>/dev/null || echo '.invarium/' >> .gitignore

2. Create .invarium/config.json:
   {"api_key": "inv_xxx...", "mcp_url": "https://mcp.invarium.dev"}

3. curl -sS https://mcp.invarium.dev/api/tracer -o .invarium/invarium_trace.py

→ Next: Call invarium_get_workflow() to load the full QA workflow.

Your IDE assistant will execute these steps automatically using its own file-writing and shell tools.

Field	Description
Account	The email address associated with your API key.
Workspace	The workspace this API key belongs to. All agents and test runs are scoped to this workspace.
Step 1	Creates `.invarium/` directory and adds it to `.gitignore`.
Step 2	Creates `.invarium/config.json` with your API key and server URL.
Step 3	Downloads the tracer library for behavioral tracing during test execution.

What Gets Created

After running the setup instructions, your project will contain:

.invarium/
  config.json          # API key and MCP URL for local tracer
  invarium_trace.py    # Behavioral trace library (do not modify)

.invarium/ is added to your .gitignore by step 1. The directory contains your API key — it should not be committed to version control.

⚠️

Do not commit .invarium/ to version control. It contains your API key. The .gitignore entry is added automatically, but verify it is present if you manage a custom .gitignore.

Examples

Basic Usage

Call with no arguments to verify the connection and set up your project:

"Connect to Invarium and verify my API key"

After Changing API Key

If you rotated your API key in the dashboard, update the INVARIUM_API_KEY in your MCP configuration, restart your MCP client, then call invarium_connect to confirm the new key works and update .invarium/config.json.

In Automated Workflows

Use invarium_connect as a preflight check in scripts before calling other tools. If the connection fails, subsequent tool calls will also fail.

Error Responses

Error	Cause	Fix
`Authentication failed: invalid API key`	The `INVARIUM_API_KEY` is missing, empty, or not a valid key.	Check that the environment variable is set correctly in your MCP config. Regenerate the key from the dashboard if needed.
`Authentication failed: key expired`	The API key has been revoked or expired.	Generate a new API key from the dashboard under API Keys.
`Connection failed: unable to reach Invarium API`	Network issue or the Invarium API is temporarily unavailable.	Check your internet connection. If the issue persists, check status.invarium.dev for service status.

See Error Codes for the full error reference.

Was this page helpful?

Overview invarium_usage