Dotnet MCP API Tester

Turn any OpenAPI spec into a repeatable, developer-friendly API testing workflow. Dotnet MCP API Tester helps teams import contracts, generate operation-level test plans, execute runs, and review results from both a REST API and a UI.

Why teams use Dotnet MCP API Tester

• Move faster with confidence: Go from spec import to executable tests in minutes, so API changes are validated early and often.
• Unify API testing workflows: Keep project setup, OpenAPI metadata, test-plan generation, and run history in one place.
• Support different environments: Start locally with file persistence, then scale to SQL-backed persistence without changing your day-to-day flow.
• Work how your team works: Use the API for automation and CI pipelines, or use the UI for interactive exploration and manual verification.

Who this is for

• Backend/API engineers who need fast feedback while building or refactoring endpoints.
• QA and test engineers who want deterministic, repeatable API run history with clear payload/result visibility.
• Platform and DevOps teams looking for a practical API quality gate that can be scripted and integrated into delivery workflows.
• Technical leads who need a shared source of truth for API behavior across contributors.

Key capabilities at a glance

• Import and version OpenAPI specs per project.
• Generate operation-scoped test plans.
• Execute runs and inspect detailed run outputs.
• Manage projects and runs through both REST endpoints and a Razor Pages UI.
• Choose between local file storage and EF Core-backed SQL persistence.

Typical use cases

• Validate new endpoints before merging feature branches.
• Regression-check critical operations after contract updates.
• Run smoke and golden-path API checks as part of release readiness.
• Give non-backend contributors a simple UI for reviewing API behavior.

Architecture overview

The solution is split into three main layers:

• ApiTester.Web: The ASP.NET Core Web API that handles project CRUD, OpenAPI imports, test-plan generation, and run execution. It exposes a REST API (plus Swagger UI) and is the source of truth for persistence configuration.
• ApiTester.Ui: A Razor Pages UI that calls ApiTester.Web using an API key. It is intended for human-driven exploration of projects and runs.
• Persistence layer (ApiTester.McpServer): Shared persistence abstractions and implementations. The Web API registers either file-based stores or EF Core-backed SQL stores based on configuration.

Persistence model

Persistence is selected at startup via the Persistence configuration section:

• File (default): Projects, OpenAPI specs, and test plans are stored as JSON in the working directory, while run results are stored as JSON files per project. The working directory comes from MCP_WORKDIR (defaults to the current directory).
• SQL (SqlServer or Sqlite): Uses EF Core with the migrations in ApiTester.McpServer. All project, spec, test plan, and run data are stored in a database.

Configure SQL persistence

Set the persistence provider and connection string (for example via environment variables):

export Persistence__Provider=SqlServer
export Persistence__ConnectionString="Server=localhost;Database=ApiTester;User Id=sa;Password=Your_password123;TrustServerCertificate=true"

For SQLite:

export Persistence__Provider=Sqlite
export Persistence__ConnectionString="Data Source=apitester.db"

Apply migrations before first run:

dotnet ef database update --project ApiTester.McpServer

Local development

dotnet restore
dotnet build -c Release
dotnet test -c Release

Testing

Run all unit/integration tests:

dotnet test

Run the security regression suite only:

./scripts/security.sh

Windows:

pwsh ./scripts/security.ps1

Run the docker-compose golden path E2E suite:

./scripts/e2e.sh

Windows:

pwsh ./scripts/e2e.ps1

Manual QA runbook and fixture data are documented in:

• docs/qa/golden-path.md
• docs/qa/test-data.md

Security docs and threat modeling resources:

• docs/security/README.md
• docs/security/threat-model.md
• SECURITY.md

Local run

One command to start the Web API + UI:

./scripts/local-run.sh

Run them separately (two terminals) if you prefer:

dotnet run --project ApiTester.Web --launch-profile "ApiTester.Web"
dotnet run --project ApiTester.Ui --launch-profile "ApiTester.Ui"

The Web API defaults to http://localhost:5000 and the UI defaults to http://localhost:5171.

Marketing site assets

The marketing site lives in ApiTester.Site. Static assets are stored under ApiTester.Site/wwwroot/images (for example logo-mark.svg, hero-illustration.svg, and pattern-grid.svg). Replace those files when updating the logo, hero illustration, or background patterns, and keep references in ApiTester.Site/Components/App.razor and the marketing page components in sync with the filenames.

UI usage

1. Start both the Web API and UI.
2. Navigate to http://localhost:5171.
3. Create a project, import an OpenAPI spec, generate test plans, and execute runs.
4. Use the Runs page to review test results and payloads.

The UI sends the API key configured in ApiTester.Ui/appsettings.json (Auth:ApiKey) to the Web API. Ensure it matches one of the keys configured in ApiTester.Web (Auth:ApiKeys).

API authentication

All /api/* endpoints require an API key header:

X-Api-Key: <your-key>

The default dev keys are listed in ApiTester.Web/appsettings.json.

API examples (curl)

Set a couple of helpers:

export API_BASE_URL=http://localhost:5000
export API_KEY=dev-local-key

Health check:

curl -H "X-Api-Key: $API_KEY" "$API_BASE_URL/health"

Version:

curl -H "X-Api-Key: $API_KEY" "$API_BASE_URL/api/version"

List projects:

curl -H "X-Api-Key: $API_KEY" "$API_BASE_URL/api/projects"

Create a project:

curl -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sample Project"}' \
  "$API_BASE_URL/api/projects"

Get a project:

curl -H "X-Api-Key: $API_KEY" "$API_BASE_URL/api/projects/<projectId>"

Import an OpenAPI spec (JSON file upload):

curl -H "X-Api-Key: $API_KEY" \
  -F "file=@./openapi.json" \
  "$API_BASE_URL/api/projects/<projectId>/openapi/import"

Get OpenAPI metadata:

curl -H "X-Api-Key: $API_KEY" "$API_BASE_URL/api/projects/<projectId>/openapi"

Generate a test plan:

curl -H "X-Api-Key: $API_KEY" \
  -X POST \
  "$API_BASE_URL/api/projects/<projectId>/testplans/<operationId>/generate"

Fetch a test plan:

curl -H "X-Api-Key: $API_KEY" \
  "$API_BASE_URL/api/projects/<projectId>/testplans/<operationId>"

Execute a run:

curl -H "X-Api-Key: $API_KEY" \
  -X POST \
  "$API_BASE_URL/api/projects/<projectId>/runs/execute/<operationId>"

List runs:

curl -H "X-Api-Key: $API_KEY" \
  "$API_BASE_URL/api/runs?projectKey=<projectKey>"

Get a run:

curl -H "X-Api-Key: $API_KEY" \
  "$API_BASE_URL/api/runs/<runId>"

Deployment and release operations

For production packaging and release hardening guidance, see:

• docs/deployment.md
• docs/release-checklist.md

Troubleshooting

API fails to start with an API key error

If you see API key authentication requires at least one key, configure at least one key under Auth:ApiKey or Auth:ApiKeys for the Web API (and UI).

UI shows 401/403 when calling the API

Ensure ApiTester.Ui/appsettings.json has an Auth:ApiKey value that matches one of the keys in ApiTester.Web/appsettings.json. Also verify ApiTesterWeb:BaseUrl matches where the Web API is running.

SQL provider config mismatch

If you set a SQL connection string but the service still uses file persistence, confirm you set Persistence:Provider and Persistence:ConnectionString. The persistence layer does not read ConnectionStrings:ApiTester for selection, so mismatched keys will silently fall back to file storage.

EF Core migrations missing tables

If the app fails on SQL queries, run the migrations:

dotnet ef database update --project ApiTester.McpServer

Smoke test

With the Web API + UI running:

./scripts/smoke-test.sh