Feature request

Description the feature

Part of the MCP meta issue #934.
Depends on #938

Expose ScanAPI run functionality as an MCP tool.

The goal of this task is to make the existing ScanAPI execution flow available through MCP while reusing current internal logic and existing execution structures.

Initial scope:

• Register a run MCP tool
• Invoke existing ScanAPI execution flow
• Reuse current scanapi run internals
• Return structured execution results suitable for MCP clients

This implementation should not introduce a separate execution path.

Is your feature request related to a problem?

After introducing the MCP server, it still does not expose useful ScanAPI functionality.

The run command is one of the primary ScanAPI capabilities and is a natural first MCP tool.

Making it available allows AI assistants and MCP clients to execute ScanAPI workflows programmatically and inspect results without parsing terminal output.

Do you have any suggestions on how to add this feature in scanapi ?

Suggested behavior:

CLI:

uv run scanapi run \
  ../examples/demo-api/scanapi.yaml \
  -c ../examples/demo-api/scanapi.conf \
  -o ../examples/demo-api/scanapi-report.html

MCP:

Tool: run

Input:
  spec_path: ../examples/demo-api/scanapi.yaml
  config_path: ../examples/demo-api/scanapi.conf
  output_path: ../examples/demo-api/scanapi-report.html
  no_report: false
  browser: false
  template: null
  log_level: INFO

The MCP interface should mirror existing CLI behavior whenever possible rather than introducing a simplified execution model.

Current CLI options:

SPEC_PATH

-o, --output-path
-nr, --no-report
-b, --browser
-t, --template
-c, --config-path
-ll, --log-level

Both should reuse the same execution flow:

scanapi run
      ↓
 existing execution flow

MCP run
      ↓
 existing execution flow

ScanAPI already builds a structured context object used by reporters:

scanapi/reporter.py

Rather than introducing a separate representation for MCP responses, this context object could be reused and adapted.

Current shape:

{
    "now": datetime.datetime(...),
    "project_name": "Snippets API",

    "results": [
        {
            "no_failure": True,
            "options": {},
            "request_node_name": "health",
            "response": <Response [200 OK]>,
            "tests_results": [
                {
                    "error": None,
                    "failure": None,
                    "name": "snippets-api::health::status_code_is_200",
                    "status": "passed",
                }
            ]
        },

        {
            "no_failure": False,
            "options": {},
            "request_node_name": "update_with_patch",
            "response": <Response [200 OK]>,
            "tests_results": [
                {
                    "error": None,
                    "failure": "response.elapsed.total_seconds() < 1",
                    "name": "snippets-api::snippets::update_with_patch::response_time_is_under_a_second",
                    "status": "failed",
                }
            ]
        }
    ],

    "scanapi_version": "2.13.2",

    "session": {
        "errors": 0,
        "failures": 2,
        "successes": 53,
        "exit_code": <ExitCode.OK: 0>,
    }
}

The MCP response could expose a lightweight summary while preserving detailed execution results:

{
  "summary": {
    "requests": 10,
    "tests": 55,
    "passed": 53,
    "failed": 2,
    "success": false
  },

  "results": [...]
}

The current context object appears to be created as part of the reporting flow. It may be worth extracting context creation into a reusable layer so it can be shared across reporters and MCP integrations.

This would allow multiple interfaces to consume the same execution result structure rather than coupling it to report generation.

Documentation

This feature should include documentation updates where applicable, including usage examples and any new MCP commands, tools, or configuration changes.

Helpful Resources

https://scrapfly.io/blog/posts/how-to-build-an-mcp-server-in-python-a-complete-guide