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 --prerelease=allow 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.

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", "--prerelease=allow", "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.

--prerelease=allow is required while the miqatools dependency is on a prerelease. Pin a release with miqa-mcp@0.2.3 if you want reproducible behavior instead of always tracking the latest.

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.

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