MIQA MCP

An MCP server that connects your AI assistant to MIQA. Ask about test runs in plain English, pull results and sample metadata, and create component versions or kick off tests — without leaving your editor or terminal.

Works with Claude Code, Cursor, and any other MCP client that speaks stdio.

Requirements

• uv (brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh)
• A MIQA server URL and API key

Quickstart

There is nothing to install — uvx downloads and runs the server on demand.

Claude Code

claude mcp add miqa-mcp \
  --scope user \
  -e MIQA_SERVER_URL=yourco.miqa.io \
  -e MIQA_API_KEY=your-key-here \
  -- uvx --refresh miqa-mcp

Confirm it registered with claude mcp list, and remove it with claude mcp remove miqa-mcp. Use --scope user to make it available everywhere, or drop it to register for the current project only.

Test a local checkout with Claude Code

Use this flow to test an unpublished branch. From the local miqa-mcp checkout, install the locked dependencies:

uv sync

Register the local executable using its absolute path and pass the credentials after the executable:

claude mcp add -s local miqa-mcp-local \
  /absolute/path/to/miqa-mcp/.venv/bin/miqa-mcp \
  -e MIQA_SERVER_URL=yourco.miqa.io \
  -e MIQA_API_KEY=your-key-here
claude mcp get miqa-mcp-local

If miqa-mcp-local is already registered, remove it first with claude mcp remove miqa-mcp-local. Restart Claude Code after registering the server. GitHub SSH access is required when the lockfile pins miqatools to a private Git commit.

Cursor, Claude Desktop, and other MCP clients

Add this to your client's MCP config file (~/.cursor/mcp.json for Cursor, claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "miqa-mcp": {
      "command": "uvx",
      "args": ["--refresh", "miqa-mcp"],
      "env": {
        "MIQA_SERVER_URL": "yourco.miqa.io",
        "MIQA_API_KEY": "your-key-here"
      }
    }
  }
}

Restart the client afterwards so it picks up the new server.

Configuration

The server uses MIQA_SERVER_URL for both REST and MCP. Supported API tools are discovered from the deployment's /mcp endpoint and added with an api_ prefix. The same MIQA_API_KEY authenticates both connections.

When the deployment reports docs_url, its documentation MCP tools are available with a docs_ prefix. docs_url contains the unlisted-share credential, so no separate authentication header is sent to the documentation MCP.

Example prompts

Once the server is connected, talk to your assistant normally:

Investigating a run

• "Show me the test chain runs for version bcftools:1.4.1."
• "What failed in run 48210? Summarize the assertions that didn't pass."
• "Pull the full report for run 48210 and group the failures by sample."
• "Which sample files went into run 48210, and where did they come from?"
• "What was the execution environment for run 48210?"

Comparing and tracking versions

• "List the last 20 versions of component 512 and tell me which ones are one-offs."
• "Has anything run through trigger abc123 in the last week? Show me the outcomes."
• "Compare the results of the two most recent runs for version bcftools:1.4.1."

Making changes

• "For trigger abc123, create a new component version using docker image myrepo/aligner:2.3.0 — show me the diff first."
• "Update the main command on trigger abc123 to add --threads 8 and preview the change."
• "Create version v2.3.0-rc1 from base version 8891, then run it through trigger abc123."

Write operations always preview first and wait for your confirmation — see Safety model.

Tools

Read-only

Writes

Most read tools accept an optional sample (datasource) ID to narrow the response to a single sample. A few tools depend on server-side feature flags and may be unavailable on older MIQA deployments.

Safety model

Both write tools are preview-first. They run as a dry run unless you explicitly opt in, so an assistant can never change or launch something on your behalf by accident.

create_component_version — By default nothing is persisted: it returns a validation verdict and a diff of the version it would create. Your assistant shows you that diff and needs your explicit go-ahead before applying it. Applying saves the new version; it never starts a test run. After a successful apply you get a link to the resource in MIQA, and the assistant will offer to preview a run for you. Its optional is_oneoff flag marks the created ComponentVersion so it is excluded from "latest version" base resolution for future creates — it does not select a base version or start any run.

run_test_trigger — Also preview-only by default. Applying creates a one-off workflow version and starts the configured test chain. It accepts one component version override and one unambiguous baseline state machine, and it does not poll the resulting run — ask for the run status separately.

These two "one-off" concepts are unrelated: create_component_version's is_oneoff marks a ComponentVersion row, while run_test_trigger's one-off is a StateMachine/workflow created for that single run. Applying run_test_trigger never changes a ComponentVersion's is_oneoff flag.

Troubleshooting