Let a coding agent build and verify LLM mocks

The DotMock MCP server gives coding agents typed tools for LLM fixtures, connection details, the request journal, sequence resets, runtime settings, and recordings. An agent can write the fixture, run your tests, and prove from the journal which fixture answered.

In this guide

Connect Claude Code, Cursor, Codex, and VS Code
The LLM tools an agent can call
The create, run, inspect, reset loop
Approval boundaries

Prerequisites

An MCP client
A team-scoped DotMock management credential
The target LLM workspace ID in $API_ID

On this page

Connect your client
LLM tools
The LLM mock loop
Offline agents with the CLI
Approval boundaries

Connect your client

The server speaks Streamable HTTP at https://mcp.dotmock.com/mcp and authenticates with a team API key in the x-api-key header. Create the key in Settings, then API keys, with only the permissions the agent needs, and keep it in the client's secret input or environment rather than in the repository.

Claude Code

claude mcp add --transport http dotmock https://mcp.dotmock.com/mcp \
  --header "x-api-key: $DOTMOCK_API_KEY"

Cursor · .cursor/mcp.json

{
  "mcpServers": {
    "dotmock": {
      "url": "https://mcp.dotmock.com/mcp",
      "headers": { "x-api-key": "${env:DOTMOCK_API_KEY}" }
    }
  }
}

VS Code · .vscode/mcp.json

{
  "inputs": [
    { "type": "promptString", "id": "dotmock-key", "description": "DotMock API key", "password": true }
  ],
  "servers": {
    "dotmock": {
      "type": "http",
      "url": "https://mcp.dotmock.com/mcp",
      "headers": { "x-api-key": "${input:dotmock-key}" }
    }
  }
}

Codex · ~/.codex/config.toml

[mcp_servers.dotmock]
url = "https://mcp.dotmock.com/mcp"
env_http_headers = { "x-api-key" = "DOTMOCK_API_KEY" }

stdio-only clients (mcp-remote)

{
  "mcpServers": {
    "dotmock": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.dotmock.com/mcp", "--header", "x-api-key:${DOTMOCK_API_KEY}"],
      "env": { "DOTMOCK_API_KEY": "<team API key>" }
    }
  }
}

LLM tools

These tools are scoped to the key's team and permissions. Inputs are validated against the same fixture schema the dashboard uses.

create_llm_fixture, update_llm_fixture, get_llm_fixture, list_llm_fixtures, reorder_llm_fixtures — author fixtures
delete_llm_fixture — requires approved: true
get_llm_connection_info — base URLs for every provider plus ready-to-paste OpenAI, Anthropic, Gemini, Vercel AI SDK, LangChain, and curl snippets; accepts session, seed, and model
get_llm_journal — filter by fixture, matched, provider, session, and since; includePayloads adds request and response bodies
reset_llm_sequences — reset counters for one session or all sessions
get_llm_runtime_settings, update_llm_runtime_settings — chaos, mode, fallback, and VCR upstreams; updates require approved: true
list_llm_recordings, promote_llm_recording — turn VCR recordings into fixtures

The LLM mock loop

A reliable agent session follows the same loop a developer would, and reports evidence from the journal rather than claiming success from its own reasoning.

1. create_api with mockType llm, or reuse the workspace in $API_ID
2. get_llm_connection_info and wire the returned base URL into the app or test config; use a unique X-Dotmock-Session and a fixed X-Dotmock-Seed
3. create_llm_fixture with match plus response, or with workflow.run.toolCalls plus a final response for tool round trips
4. Run the application or test suite
5. get_llm_journal filtered by session to confirm which fixture answered each request and that nothing was unmatched
6. Adjust fixtures, reset_llm_sequences, and run again
7. Optionally enable VCR, then list_llm_recordings and promote_llm_recording to capture real answers as fixtures

Example prompt

Using the DotMock MCP server and API $API_ID: add a fixture that answers
"cancel my order" with a cancel_order tool call and then a confirmation,
run `npm test -- agent`, and show me the journal entries for session agent-1.
Do not change runtime settings.

Offline agents with the CLI

For local mode there is no hosted API to call through MCP. Agents use the CLI instead: dotmock init --llm, edit dotmock.yaml, dotmock serve --detach, run tests, then dotmock llm journal <subdomain> --local and dotmock llm reset <subdomain> --local. dotmock llm connect <subdomain> --local prints SDK snippets and environment variables.

Approval boundaries

Reading, fixture authoring, reordering, promotion, and sequence resets run directly within the key's scope. Deleting fixtures and changing runtime settings, including chaos and VCR upstreams, require an explicit approved: true that the agent should only send after you confirm. The management key authorizes these tools; the application under test never needs it.