Connect Claude or another AI agent to write and seed mock scenarios conversationally — no manual dashboard editing

AI Agent (MCP)

An AI agent (like Claude Code) can author and seed mock scenarios for you. The agent reads your projects and endpoints, writes scenario rules and response bodies, and pushes them to the dashboard — all from natural language prompts.

The agent cannot delete scenarios or modify your endpoint definitions. It can create and update scenarios, including — with an explicit flag — the default scenario.

What the agent can do

Capability	Example
List your projects	"What Mock Alpha projects do I have?"
List a project's endpoints and their scenario keys	"Show me the endpoints in my payment service"
Read one endpoint's full detail (scenarios + active response snapshot)	"What does the real response for `/payments/charge` look like?"
Create or update one scenario on one endpoint	"Add a 401 scenario to `/login` when the token is invalid"
Batch-apply the same preset(s) across many endpoints	"For every endpoint in the auth service, add a 500 error scenario"
Preview a batch change before writing	"Show me what you would create, then do it"

The agent cannot:

Delete scenarios
Modify endpoints (add paths, change methods)
Overwrite a default scenario without an explicit confirmation flag
Run tests
Create API keys or other account settings

Generate an MCP token

Log in to https://mock-alpha.aprix.site
Click the Settings icon in the top-right
Under Create a token, enter a name for your agent (e.g., "Work laptop", "CI pipeline")
Click Generate
Copy the token immediately — it only appears once

Connect your agent

Use the claude mcp add command shown in Settings:

claude mcp add --transport http mock-alpha https://mock-alpha.aprix.site/api/mcp --header "Authorization: Bearer <token>"

Replace <token> with the token you just copied.

Then restart your agent (or reload if it's a web app), and the five tools become available.

The five tools

Tool	Purpose
`list_projects`	List the projects you're a member of (`{id, name, role}` each). Call this first — every other tool needs a `projectId` from here.
`list_endpoints`	List a project's endpoints together with the scenario keys each one already has. Optional `serviceName`/`method` filters. Check the existing keys before creating scenarios so you don't duplicate what's there.
`get_endpoint`	Full context for one endpoint: its scenarios (with match rules and priority) and the active response snapshot. Use the snapshot's schema and sample to write response bodies whose shape matches the real API instead of inventing a generic one.
`upsert_scenario`	Create or update one scenario on one endpoint. Reachable from tests with the header `X-Mock-Scenario: <scenarioKey>`. Overwriting an endpoint's default scenario requires passing `overwrite: true` explicitly — without it, the call is rejected.
`seed_error_scenarios`	Apply the same preset(s) verbatim to many endpoints at once — an explicit list of endpoint IDs, a whole service, or the whole project. Takes a `dryRun: boolean` parameter (not a separate tool) that reports the plan without writing anything. Automatically skips (doesn't fail on) any endpoint whose targeted scenario key is currently its default — use `upsert_scenario` with `overwrite: true` for those instead.

seed_error_scenarios applies each preset's responseBody as-is to every endpoint it targets — it does not reshape the body per endpoint. If different endpoints need differently-shaped bodies, call upsert_scenario once per endpoint instead, using get_endpoint's snapshot to inform each body.

Example prompts

List endpoints in a service

"List my Mock Alpha projects, then show me all endpoints in the payment service"

Projects: [Acme Mobile, Acme Web]

Payment service endpoints:
- POST /payments/charge — 2 scenarios (success, error_500)
- GET /payments/charges — 1 scenario (success)
- POST /payments/refund — 1 scenario (success)

Add a single scenario

"For the POST /payments/charge endpoint, add a scenario where the card is declined. The response should be a 400 with { "error": "Card declined", "code": "insufficient_funds" }"

The agent:

Calls list_endpoints to find the endpoint
Optionally calls get_endpoint to check the response shape
Calls upsert_scenario with statusCode: 400 and the response body (e.g. scenarioKey: "card_declined")

Bulk authoring

"For every endpoint in the auth service, add a 401 scenario when the token is missing, with { "error": "Unauthorized" }. Show me the dry run first."

The agent:

Calls seed_error_scenarios with target: { serviceName: "auth" }, the preset, and dryRun: true
Shows you the plan (which endpoints get a create vs. an update, and which are skipped because the key is already their default)
Calls it again without dryRun once you confirm

Security

Token scope

A token covers all projects you are a member of. It is different from a project's API key:

Token type	Scope	Powers	Use case
MCP token	All your projects	Create/update scenarios	AI agent, CI pipeline
API key	One project	Mock requests (GET), limited	Mobile app (embedded)

An API key embedded in your app has no write access. An MCP token has no API key powers.

Revoking a token

Go to Settings → Your tokens and click the trash icon next to a token. Any agent using it stops working immediately.

Do this if:

You rotate credentials
A token is leaked
You no longer need an agent for a project

Audit trail

Every scenario an agent creates, updates, or seeds is recorded in the project's activity log under your account — the same as a change made manually in the dashboard. Each MCP-originated entry is also internally tagged with the token's name, so you have a record of which credential made the change if you ever need to check.

Limitations (intentional)

The agent cannot:

Delete scenarios — all changes are additive, reducing the risk of accidental loss
Modify endpoints — the endpoint schema is locked; use the dashboard if you need new paths
Overwrite the default scenario without confirmation — upsert_scenario rejects the write unless you explicitly pass overwrite: true (a batch seed_error_scenarios call never overwrites a default at all; it skips those endpoints)
Batch delete — even if it could delete, there is no bulk removal to prevent accidents

These limits exist to reduce the surface area for mistakes. The dashboard is the source of truth for destructive operations.

Troubleshooting

"Token not found" or "Unauthorized"

Verify the token was copied correctly (it starts with mcp_)
Check the connection command: claude mcp add --transport http mock-alpha https://mock-alpha.aprix.site/api/mcp --header "Authorization: Bearer <token>"
If the token is old, revoke it and generate a new one
Restart the agent or reload the app after adding the MCP server

"Endpoint not found"

Make sure you spell the endpoint path correctly (case-sensitive)
Use the list_endpoints tool (with the projectId from list_projects) to see the exact paths and IDs
Paths use the / style from your mock requests (e.g., /api/login not api/login)

Agent is slow

Creating many scenarios in one batch can take time. Break large batches into smaller groups if needed, or use seed_error_scenarios for identical presets across many endpoints instead of calling upsert_scenario one at a time.

AI Agent (MCP)

On this page