There are two ways to put an AI assistant to work with Traffic Parrot, and they combine well:
The quick start walks the whole flow end to end with Claude Code and a copy-paste starter prompt: the agent fetches the schema and the helper policy, writes a mapping, checks it, loads it, and proves the mock works. Before you run it, make sure Traffic Parrot runs on your own machine or a trusted network. The sections after the quick start explain each part in more depth.
This page is the hands-on guide. For the wider picture of what Traffic Parrot offers AI agents, see AI and agent capabilities.
By default, Traffic Parrot does not ask for a password: anyone who can reach the management port (8080 by default, the port you configure Traffic Parrot on) or the simulator's /__admin endpoint can load a mapping, and a loaded mapping starts answering requests immediately. Some mappings can also use helpers that run code on the machine.
This matters more when an AI agent writes the mocks. The mappings come from a language model rather than a person, and what the model writes can be influenced by the text in the files you give it. Your safety net is checking the work before it goes live. Running on your own machine or a trusted network means that if something slips through, it only affects your machine, not a shared environment.
This walkthrough uses Claude Code, a coding agent that runs in your terminal; any agent that can fetch a URL and call an HTTP API follows the same flow with the same starter prompt. You need:
mkdir train-mock
cd train-mock
claudeCopy this prompt as a starting point and adapt it as needed:
Download the Train Travel API sample contract from https://raw.githubusercontent.com/bump-sh-examples/train-travel-api/main/openapi.yaml and read it. Fetch the Traffic Parrot mapping schema from http://localhost:8080/schemas/http-mapping.schema.json and the helper policy from http://localhost:8080/helper-policy.json Generate a Traffic Parrot mapping for GET /stations in a file called stations-mapping.json. It must conform to the mapping schema, must not use any helper denied by the helper policy, and should return a realistic response based on the contract. Validate stations-mapping.json against the schema, show me the mapping and the validation result, and wait for my approval. Once I approve, load the mapping with a POST to http://localhost:8080/api/http/__admin/mappings and then call http://localhost:8081/stations to prove the mock works.
Claude Code asks before it runs each command, so you stay in control. When it shows you stations-mapping.json and the validation result, read the mapping before approving: once loaded, it starts answering requests immediately.
After you approve, Traffic Parrot confirms the mapping was created (201 Created) and the final call to http://localhost:8081/stations returns the station list: your mock is live.
Grounding the agent means giving it the reference material it needs, so it works from facts instead of guessing. Put three things into the agent's context, then let it generate:
Those three are the minimum. Point the agent at your production code and your API documentation as well and it writes very realistic mocks: the specification gives the shape of requests and responses, the documentation how the API behaves, and the code the values and edge cases that never made it into either. Once you are working with your own API, add lines like these to the prompt and point them at what you have:
Also read the production code that implements the API (in ./src) and the API documentation (in ./docs). Reuse what you find there in the mocked responses: the real field names, values in the formats the systems actually exchange, and the error responses the API really returns. The mock should be hard to tell apart from the live API.
Everything you add becomes input to the model, so the warning below applies to it as much as to the contract.
The mapping schema spells out exactly what a valid mapping looks like: which fields exist, which are required, and what values they can take. With it in hand, the agent guesses less and can check its own work. Your instance serves its schemas itself, with a machine-readable index at http://localhost:8080/schemas/index.json: one entry per mapping format, with the directory that format's mapping files live in. They ship inside Traffic Parrot, so they always match the version you are running.
Mappings can use Handlebars helpers: small built-in functions that make a response dynamic, for example inserting a random value or today's date. Two of them, executeProcess and evaluate, can run arbitrary code on the machine and must never appear in a generated mapping. The helper policy your instance serves at http://localhost:8080/helper-policy.json names them. It is a deny-list, so anything it does not name is allowed, and the helper-policy check enforces it when you validate.
Everything you hand the agent, including the contract, becomes input to a language model. Text hidden in a description or an example could nudge the agent toward a denied helper or a response that leaks data. Traffic Parrot does not check a mapping between loading it and it going live, so the checks are yours to run: check against the schema, read the mapping before loading it, and run the Traffic Parrot checks.
The checks the agent runs are your first guard; trafficparrot validate is a second, independent one you run by hand or in CI. It checks a folder of mappings without starting the server, compares them with your contracts, and fails when a mapping mocks something the contract does not describe or part of the contract has no mapping at all:
trafficparrot validate /path/to/files-rootSee the validate CLI reference and the messaging coverage check for details.
For generated mappings, also enable the helper-policy check: it fails if a mapping uses a denied helper, and it reads the mappings without running them, so it even catches a helper hidden inside another one. It is off by default (hand-written mappings legitimately use those helpers):
trafficparrot validate /path/to/files-root \
-Dtrafficparrot.validate.helper.policy.check=truePoint the application you are testing at the stub port instead of the real API: change its base URL to http://localhost:8081 (or wherever your simulator runs). Your application now gets the mocked responses, so you can test without the real system being available.
The generated mappings are plain JSON files, so you can also:
Everything above has the agent work with mapping files. Traffic Parrot also speaks the Model Context Protocol (MCP), so an assistant can work with the running instance itself: read the mappings it is serving, the requests that have arrived and the scenarios defined, and change them, without you pasting JSON into the conversation or copying it back out.
Traffic Parrot serves the endpoint itself: nothing extra to install, no separate process. It is on the management port (8080 by default) and, unlike the rest of the management API, not under /api:
http://localhost:8080/mcp
The trusted-network guidance above matters more here: six of the twelve tools change what the instance is serving. Anything that can lose work takes dryRun, and it defaults to true: a call that leaves it out previews and changes nothing, so an assistant shows you what it would do before it does it. A mapping change is written through to the selected scenario's mapping files. The tools themselves, with their arguments and what each preview returns, and the protocol detail (the handshake, the headers, and the curl calls to check the endpoint by hand) are on the MCP endpoint reference page; your client shows the same tool catalogue.
The install directory ships AGENTS.md, a brief written for the assistant rather than for you: the endpoint, how to register it in Claude Code, GitHub Copilot CLI, Cursor and Antigravity, the ground rules, the twelve tools and the workflows an assistant is most often asked for. Copy it into the repository you work in, or point the assistant at it, and the assistant starts out knowing all of that without you explaining it in every conversation. If your client does not pick up AGENTS.md by name, name the file in your prompt or reference it from the client's own instructions file.
Claude Code, from the folder you work in:
claude mcp add --transport http traffic-parrot http://localhost:8080/mcpThe same server as JSON, here in Claude Code's .mcp.json; other clients read the same mcpServers shape from their own configuration file:
{
"mcpServers": {
"traffic-parrot": { "type": "http", "url": "http://localhost:8080/mcp" }
}
}Then ask the assistant what the instance is serving. In Claude Code, /mcp shows the connection and the twelve tools.
By default the endpoint accepts requests from the machine Traffic Parrot is running on and refuses everything else, which is the common case: the assistant runs where you do. Nothing to configure, and no token to manage.
Traffic Parrot in a container with a published port is the usual exception: its requests arrive from the container network, not loopback, so the default refuses them. Set both of these in trafficparrot.properties (see the Configuration Reference) and restart:
trafficparrot.mcp.authenticator=BEARER_TOKEN
trafficparrot.mcp.token=a-secret-of-your-choosingEvery request must then carry Authorization: Bearer <token>, which the client sends for you:
claude mcp add --transport http traffic-parrot http://localhost:8080/mcp \
--header "Authorization: Bearer a-secret-of-your-choosing"A refused request says which property to change. The reference's refusal table covers the token rules, the web UI login, and how to tell the refusals apart.