rust_browser/_bmad/tea/testarch/knowledge/pact-mcp.md

Pact MCP Server (SmartBear)

Principle

Use the SmartBear MCP server to enable AI agent interaction with PactFlow/Pact Broker during contract testing workflows. The MCP server provides tools for generating pact tests, fetching provider states, reviewing test quality, and checking deployment safety — all accessible through the Model Context Protocol.

Rationale

Why MCP for contract testing?

• Live broker queries: AI agents can fetch existing provider states, verification results, and deployment status directly from PactFlow
• Test generation assistance: MCP tools generate consumer and provider tests based on existing contracts, OpenAPI specs, or templates
• Automated review: MCP-powered review checks tests against best practices without manual inspection
• Deployment safety: can-i-deploy checks integrated into agent workflows for real-time compatibility verification

When TEA uses it

• test-design workflow: Fetch existing provider states to understand current contract landscape
• automate workflow: Generate pact tests using broker knowledge and existing contracts
• test-review workflow: Review pact tests against best practices with automated feedback
• ci workflow: Reference can-i-deploy and matrix tools for pipeline guidance

Available Tools

#	Tool	Description	When Used
1	Generate Pact Tests	Create consumer/provider tests from code, OpenAPI, or templates	automate workflow
2	Fetch Provider States	List all provider states from broker for a given consumer-provider pair	test-design, automate
3	Review Pact Tests	Analyze tests against contract testing best practices	test-review
4	Can I Deploy	Check deployment safety via broker verification matrix	ci workflow
5	Matrix	Query consumer-provider verification matrix	ci, test-design
6	PactFlow AI Status	Check AI credits and permissions (PactFlow Cloud only)	diagnostics
7	Metrics - All	Workspace-wide contract testing metrics	reporting
8	Metrics - Team	Team-level adoption statistics (PactFlow Cloud only)	reporting

Installation

Config file locations

Tool	Global Config File	Format
Claude Code	~/.claude.json	JSON (mcpServers)
Codex	~/.codex/config.toml	TOML ([mcp_servers])
Gemini CLI	~/.gemini/settings.json	JSON (mcpServers)
Cursor	~/.cursor/mcp.json	JSON (mcpServers)
Windsurf	~/.codeium/windsurf/mcp_config.json	JSON (mcpServers)
VS Code (Copilot)	.vscode/mcp.json	JSON (servers)

Claude Code tip: Prefer the claude mcp add CLI over manual JSON editing. Use -s user for global (all projects) or omit for per-project (default).

CLI shortcuts (Claude Code and Codex)

# Claude Code — use add-json for servers with env vars (-s user = global)
claude mcp add-json -s user smartbear \
  '{"type":"stdio","command":"npx","args":["-y","@smartbear/mcp@latest"],"env":{"PACT_BROKER_BASE_URL":"https://{tenant}.pactflow.io","PACT_BROKER_TOKEN":"<your-token>"}}'

# Codex
codex mcp add smartbear -- npx -y @smartbear/mcp@latest

JSON config (Gemini CLI, Cursor, Windsurf)

Add a "smartbear" entry to the mcpServers object in the config file for your tool:

{
  "mcpServers": {
    "smartbear": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@smartbear/mcp@latest"],
      "env": {
        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
        "PACT_BROKER_TOKEN": "<your-api-token>"
      }
    }
  }
}

Codex TOML config

Codex uses TOML instead of JSON. Add to ~/.codex/config.toml:

[mcp_servers.smartbear]
command = "npx"
args = ["-y", "@smartbear/mcp@latest"]

[mcp_servers.smartbear.env]
PACT_BROKER_BASE_URL = "https://{tenant}.pactflow.io"
PACT_BROKER_TOKEN = "<your-api-token>"

Note the key is mcp_servers (underscored), not mcpServers.

VS Code (GitHub Copilot)

Add to .vscode/mcp.json (note: uses servers key, not mcpServers):

{
  "servers": {
    "smartbear": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@smartbear/mcp@latest"],
      "env": {
        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
        "PACT_BROKER_TOKEN": "${input:pactToken}"
      }
    }
  }
}

Note

: Set either PACT_BROKER_TOKEN (for PactFlow) or PACT_BROKER_USERNAME+PACT_BROKER_PASSWORD (for self-hosted). Leave unused vars empty.

Required Environment Variables

Variable	Required	Description
PACT_BROKER_BASE_URL	Yes (for Pact features)	PactFlow or self-hosted Pact Broker URL
PACT_BROKER_TOKEN	For PactFlow / token auth	API token for broker authentication
PACT_BROKER_USERNAME	For basic auth (self-hosted)	Username for basic authentication
PACT_BROKER_PASSWORD	For basic auth (self-hosted)	Password for basic authentication

Authentication: Use token auth (PACT_BROKER_TOKEN) for PactFlow. Use basic auth (PACT_BROKER_USERNAME + PACT_BROKER_PASSWORD) for self-hosted Pact Broker instances. Only one auth method is needed.

Requirements: Node.js 20+

Pattern Examples

Example 1: Fetching Provider States During Test Design

When designing contract tests, use MCP to query existing provider states:

# Agent queries SmartBear MCP during test-design workflow:
# → Fetch Provider States for consumer="movie-web", provider="SampleMoviesAPI"
# ← Returns: ["movie with id 1 exists", "no movies exist", "user is authenticated"]
#
# Agent uses this to generate comprehensive consumer tests covering all states

Example 2: Reviewing Pact Tests

During test-review workflow, use MCP to evaluate test quality:

# Agent submits test file to SmartBear MCP Review tool:
# → Review Pact Tests with test file content
# ← Returns: feedback on matcher usage, state coverage, interaction naming
#
# Agent incorporates feedback into review report

Example 3: Can I Deploy Check in CI

During CI workflow design, reference the can-i-deploy tool:

# Agent generates CI pipeline with can-i-deploy gate:
# → Can I Deploy: pacticipant="SampleMoviesAPI", version="${GITHUB_SHA}", to="production"
# ← Returns: { ok: true/false, reason: "..." }
#
# Agent designs pipeline to block deployment if can-i-deploy fails

Key Points

• Per-project install recommended: Different projects may target different PactFlow tenants — match TEA's per-project config philosophy
• Env vars are project-specific: PACT_BROKER_BASE_URL and PACT_BROKER_TOKEN vary by project/team
• Node.js 20+ required: SmartBear MCP server requires Node.js 20 or higher
• PactFlow Cloud features: Some tools (AI Status, Team Metrics) are only available with PactFlow Cloud, not self-hosted Pact Broker
• Complements pactjs-utils: MCP provides broker interaction during design/review; pactjs-utils provides runtime utilities for test code

Related Fragments

• pactjs-utils-overview.md — runtime utilities that pact tests import
• pactjs-utils-provider-verifier.md — verifier options that reference broker config
• contract-testing.md — foundational contract testing patterns

Anti-Patterns

Wrong: Using MCP for runtime test execution

# ❌ Don't use MCP to run pact tests — use npm scripts and CI pipelines
# MCP is for agent-assisted design, generation, and review

Right: Use MCP for design-time assistance

# ✅ Use MCP during planning and review:
# - Fetch provider states to inform test design
# - Generate test scaffolds from existing contracts
# - Review tests for best practice compliance
# - Check can-i-deploy during CI pipeline design

Source: SmartBear MCP documentation, PactFlow developer docs