MCP Integration

API & MCP

Plum ships an MCP server built into the backend, over Streamable HTTP. Any MCP-compatible AI client — Claude Desktop, Claude Code, Cursor, and others — can connect and drive the whole loop: author test cases, trigger runs, and read back reports, replays and logs.

Keys

There are two ways to authenticate:

Key	Acts as	Scope
Per-member key (Settings → API & MCP)	the member who created it, with that member's role	the project it was created in
PLUM_MCP_KEY (server env var, for CI)	the owner	the whole instance

The same key authenticates the plain REST API, not only the MCP endpoint, so it is a full-access credential at your role level: at owner or admin it can create users, change project settings and delete suites. Treat it like your password.

A member's key is personal. Regenerating it invalidates the old one immediately. Everything the agent creates or runs through a key is tagged <name> (MCP) in the Activity Logs and on the rows it touches.

Connecting a client

Settings → API & MCP shows a ready-to-paste config for your project. The shape:

{
  "mcpServers": {
    "plum-your-project": {
      "type": "http",
      "url": "https://api.plum.example.com/mcp",
      "headers": {
        "Authorization": "ApiKey plum_live_…"
      }
    }
  }
}

Add it to your client's MCP config (claude_desktop_config.json, .cursor/mcp.json, Claude Code's .mcp.json, etc.). The server name plum-<slug> keeps two projects apart if you add a second key as a second server.

Tools

Grouped by area:

Test Repository

• list_test_suites, get_test_suite, create_test_suite, update_test_suite, delete_test_suite
• create_test_case, get_test_case, update_test_case, delete_test_case, set_test_steps
• export_test_cases — CSV (one row per step) or re-importable JSON; scope: whole repo, one suite, or one test run (with recorded results)

Runs and reports

• run_tests — trigger a run and wait for the result. Takes a tag expression, browser, workers, a per-run baseUrl (for PR previews — use host.docker.internal for a local app), and testRunId to mark a manual run's automated cases.
• get_run_status — poll a run started by run_tests
• list_reports, get_report_summary, get_report_scenario_detail, get_report_logs
• export_report — CSV or a minimal JSON summary

Projects and users (subject to the key's role)

• list_projects, create_project, update_project
• list_users, create_user, update_user

What it's good for

• "Draft a suite for the checkout flow from this PRD" → the agent creates the suite, cases and structured steps.
• "Run the smoke tests against this preview URL and tell me what broke" → run_tests with baseUrl, then get_report_summary / get_report_scenario_detail.
• "Turn these three failed scenarios into repository cases" → create_test_case + set_test_steps from the report detail.

CI vs MCP

For a fire-and-forget CI trigger, the plain REST endpoint is simpler. Use MCP when you want an agent to reason over the results and act on them.

Using the key without an MCP client

Nothing about the key is MCP-specific. The same value works as a plain API key against any Plum endpoint, which is how a CI job triggers a run:

curl -X POST https://api.plum.example.com/trigger \
  -H "Authorization: ApiKey $PLUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": "@smoke", "browser": "chromium", "workers": 2 }'

See Integrations for the full CI example. For an owner-scoped instance key, set PLUM_MCP_KEY on the server instead of minting a personal one.