Skip to main content

Model Context Protocol (MCP)

Proofarc ships an MCP server (proofarc-mcp) so an MCP-aware LLM client — Claude Desktop, claude.ai's remote-MCP feature, IDE plugins — can drive the platform with tool calls instead of HTTP curl.

A demo flow that used to be a 100-line bash script now collapses to one prompt:

Explore the apps under our User Management Platform project, read each repo, generate appropriate tests, run them in the cloud environment, and report what failed.

Claude chains MCP tool calls against the Proofarc server (and, optionally, the official GitHub MCP server for source-code reading) and the platform does the work.

What's exposed​

173 tools in 16 categories. Every tool that takes a project / environment / scenario / pipeline reference accepts a name or an integer id — the LLM doesn't need to look IDs up first. Full signatures + response shapes live in tools-reference; the table below is the one-line orientation.

GroupToolPurpose
explorelist_projectsList visible projects.
explorelist_project_applicationsList apps under a project (name or id) — git URLs included.
explorelist_environmentsList environments, optionally scoped to a project.
explorefind_scenariosSearch API scenarios by name, tag (static tags field with execution-history fallback), or auth type. Response includes tags.
explorefind_ui_testsSearch UI tests by name or tag (static tags field).
explorefind_ui_test_suitesList UI test suites by name. Use before run_ui_test_suite.
explorelist_pipelinesList pipelines, optionally scoped to a project.
actcreate_api_scenarioAuthor an API test scenario.
actexecute_scenarioRun a single scenario; returns execution id.
actrun_ui_testRun a previously-authored UI test on one or more engines (drivers × browsers Cartesian).
actrun_by_tagFan-out runner — queue every scenario and/or UI test matching given tags. Supports dry_run.
actrun_pipelineKick off a pipeline run by name or id.
reportget_execution_statusStatus payload. Each kind="ui_job" item carries a typed result envelope — resultKind (SECURITY_FINDINGS/CRAWL_INVENTORY/PERF_METRICS/UI_AUTOMATION/MOBILE_AUTOMATION/SCRIPT_OUTPUT) + a bounded, self-describing result (read this first). Legacy findings/reportOutput/rawOutput are kept but stubbed only when large (>8KB), to stay under the MCP 1MB cap.
reportsummarize_executionOne-screen natural-language summary.
reportget_crawl_resultsPaginated read of crawl results — index of pages, drill into one page for elements. Companion to get_execution_status on crawl jobs.
ui_authoringcrawl_uiSubmit a Playwright crawl that discovers per-page elements.
ui_authoringdiscover_form_fieldsOne-URL probe for login-page input schema.
ui_authoringrecommend_engineProbe a URL's tech stack and recommend WEBDRIVER / PLAYWRIGHT / HTMLUNIT.
ui_authoringvalidate_ui_test_yamlPre-flight schema check on a draft UI test YAML.
ui_authoringcreate_ui_test_from_yamlPersist a validated YAML as a UI test record. driver optional → engine-agnostic.
ui_authoringrun_ui_test_suiteRun every test in a suite, optionally fanned out across engines.
api_authoringparse_swaggerRead-only preview of a Swagger doc's endpoint list.
api_authoringcreate_scenario_from_swaggerBulk-generate an API scenario from a Swagger URL.
api_authoringvalidate_scenario_yamlPre-flight schema check on an API scenario YAML draft.
api_authoringcreate_scenario_from_yamlPersist a hand-drafted API scenario YAML.

1 resource template:

  • proofarc://execution/{execution_id} — full scenario execution payload.

Progressive narrowing​

Tools never raise on ambiguous input. Instead they return a structured prompt the LLM can relay to the user:

{
  "reason":     "ambiguous" | "not_found" | "missing_required",
  "ask_user":   "Which environment? Available: dev, staging, prod.",
  "candidates": [{"id": 11, "name": "dev"}, {"id": 12, "name": "staging"}, ...],
  "scoped_by":  {"project": "payments"}
}

Each round narrows the search. A request like "run the smoke tests on staging" typically converges in 1–3 turns:

TurnTool callResult
1run_by_tag(tags=["smoke"])ask: "Which environment?" + candidates
2run_by_tag(tags=["smoke"], environment="staging")ask: "Smoke tests exist in 2 projects: payments, auth. Which?"
3run_by_tag(tags=["smoke"], environment="staging", project="payments"){queued: [Login flow, Cart], dry_run: false}

Pass dry_run=true to run_by_tag to preview what would execute without queuing — useful for human confirmation before pulling the trigger.

Tag model​

Both UiTest and ApiScenario have static tags columns (the latter added in release#79+#136), so find_ui_tests(tags=…) and find_scenarios(tags=…) are exact filters on the entity. For API scenarios with empty static tags (legacy data), the resolver falls back to scanning execution history, and each match is annotated with match_source: "static_tags" or "execution_history". Both find_* responses include tags directly so the agent can call run_by_tag without a second lookup.

Two transports​

TransportUse caseAuth model
stdio (default)Claude Desktop running on your laptop.Server holds platform creds, calls /api/auth/login, caches the JWT.
http (SSE/streamable)claude.ai remote MCP, IDE plugins, server-side LLM apps.Caller passes Authorization: Bearer <platform-jwt>. Server passes it through.

Both transports register the same tools — there is no functional difference at the LLM-facing surface.

Where it runs​

  • Local laptop: pip install proofarc-mcp → proofarc-mcp --transport stdio, spawned by Claude Desktop.
  • Cloud (app.proofarc.ai): the platform Helm chart deploys an mcp-agent pod by default. Public endpoint is https://app.proofarc.ai/mcp/ (SSE/streamable).

Why no inline credentials in tool calls?​

Tools like create_api_scenario accept auth_config but the recommended pattern is to leave it null and reference an environment credential tag. Why: credential management lives in the environment's vault (docs/AUTH_HANDLING.md). The MCP server inherits the same rules as the platform UI — no special path, no hardcoded secrets in LLM prompts.

Next steps​