aimock — mock everything your AI app talks to

Deterministic mock infrastructure for AI apps

Start with LLM mocking. Add MCP, A2A, vector, and more when you need them. The aimock suite grows with your stack.

$ npx -p @copilotkit/aimock llmock -f ./fixtures
or
$ docker run -v $(pwd)/fixtures:/fixtures -p 4010:4010 ghcr.io/copilotkit/aimock -h 0.0.0.0 -f /fixtures

Or install as a library: npm install @copilotkit/aimock

fixture.json 
{
  "match": {
    "userMessage": "Hello"
  },
  "response": {
    "content": "Hi there! How can I help?"
  },
  "opts": {
    "chunkSize": 10,
    "latency": 1000
  }
}
terminal

Teams building on aimock

OpenClaw The Unwind AI Composio Karakeep Mastra AG-UI Octelium TanStack CortexKit Atomic Strata Skybridge Zoo Code Hashbrown OpenStory Tensor Foundry Dawn AI Mattermost botiverse Flight Finder Selene Supaterm Bodhi xskill Marie AI Testomat.io Opilot Covel Agent Skill Exchange Ember AI Ant Chat Deepnote
Record & Replay

From zero to fixtures in one command

1

Record

Proxy unmatched requests to real APIs and capture every response.

2

Save

Fixtures written to disk automatically as clean, editable JSON.

3

Replay

Deterministic responses in CI, forever. No API keys, no flakiness.

Learn about Record & Replay →
terminal 
$ npx -p @copilotkit/aimock llmock --record --provider-openai https://api.openai.com

⚡ Listening on http://localhost:4010

⚠ NO FIXTURE MATCH — proxying to
  https://api.openai.com/v1/chat/completions

✓ Recorded → fixtures/recorded/openai-2026-03-31T22:15:00.json

⚡ Fixture match — replaying from disk

Your AI app talks to more than just LLMs.
aimock mocks all of them.

🔌 MCP Tools
🤝 A2A Agents
🖥 AG-UI
📦 Vector DBs
🔍 Search & Rerank
🛡 Moderation

One JSON config. One port. Every service your AI app depends on.

aimock.json 
{
  "llm": {
    "fixtures": "./fixtures/llm",
    "providers": ["openai", "claude", "gemini"]
  },
  "mcp": {
    "tools": "./fixtures/mcp/tools.json",
    "resources": "./fixtures/mcp/resources.json"
  },
  "a2a": {
    "agents": "./fixtures/a2a/agents.json"
  },
  "vector": {
    "provider": "pinecone",
    "fixtures": "./fixtures/vector"
  }
}
terminal 
$ npx @copilotkit/aimock --config aimock.json

⚡ aimock v1.46.0

✓ LLM    mounted at  /v1/chat/completions
✓ LLM    mounted at  /v1/messages
✓ LLM    mounted at  /v1/embeddings
✓ MCP    mounted at  /mcp/tools/*
✓ A2A    mounted at  /a2a/agents/*
✓ Vector mounted at  /vectors/*

⚡ Listening on http://localhost:4010
   6 services · 24 fixtures loaded

Everything you need

📡

Every Major LLM Provider

OpenAI, Claude, Gemini, Gemini Interactions, Bedrock, Azure, Vertex AI, Ollama, Cohere, OpenRouter, ElevenLabs — full streaming and embeddings support for every provider.

🔌

MCP Protocol

Mock tools, resources, and prompts with full session management. Script each test's tool answers in its fixture file: ordered results, exact-argument checks, and a closed-world mode that fails on any undeclared tool.

🤝

A2A Protocol

Agent cards, message routing, and SSE streaming. Mock multi-agent interactions with deterministic responses.

🖥

AG-UI Protocol

Mock agent-to-UI event streams for CopilotKit frontend testing.

📦

Vector Databases

Pinecone, Qdrant, and ChromaDB compatible. Mock similarity search, upserts, and index operations with fixtures.

💥

Chaos Testing

Transport faults (drop, malformed, disconnect, 429) and model misbehavior: broken tool-call JSON, schema violations, unknown tools, and max-tokens cutoffs in every provider's real wire format.

🎨

Multimedia APIs

Image generation and editing, text-to-speech (OpenAI + ElevenLabs), audio transcription and translation, non-speech audio generation, and video generation — mock every multimedia endpoint with fixtures.

🧪

Vitest & Jest Plugins

Zero-config useAimock() with auto server lifecycle, env var patching, and match count reset.

📊

Drift Detection

Fixtures stay accurate as providers evolve. Fixes ship before your tests break.

Your mocks never go stale

LLM providers change their response formats without warning. aimock catches it within 24 hours and ships the fix before your tests break.

1

Real API calls

Daily CI hits actual OpenAI, Anthropic, Gemini endpoints to detect response format changes.

2

Compare & detect

Response schemas are validated against aimock's builders. Any drift is flagged automatically.

3

Fix & ship

Drift detected → fixtures, builders, skills, and docs updated → PR shipped. Always current, within a day.

Learn about drift detection →

How aimock compares

LLM and protocol mocking

Capability aimock MSW VidaiMock mock-llm piyook/llm-mock mokksy/ai-mocks MockServer WireMock
Cross-process interception Real server ✓ In-process only ✓ ✓ (Docker) ✓ ✓ (Ktor) ✓ ✓
Chat Completions SSE Built-in ✓ manual ✓ ✓ ✓ ✓ ✓ ND
Responses API SSE Built-in ✓ manual ✓ ✗ ✗ ✓ ✓ ND
Claude Messages API Built-in ✓ manual ✓ ✗ ✓ ✓ ✓ ND
Gemini streaming Built-in ✓ manual ✓ ✗ ✓ ✓ ✓ ND
Multi-provider support 13 providers (15 API surfaces) ✓ manual 12 providers OpenAI only OpenAI only 5 providers ✓ ND
OpenRouter router / fallback simulation Deterministic ✓ ✗ ✗ ✗ ✗ ✗ partial ND
WebSocket APIs Built-in ✓ ✗ ✗ ✗ ✗ ✗ partial partial
Embeddings API Built-in ✓ ✗ ✓ ✗ ✓ ✓ ✓ ND
Image generation Built-in ✓ ✗ ✓ ✗ ✗ ✗ ✗ ND
Image editing Built-in ✓ ✗ ✗ ✗ ✗ ✗ ✗ ND
Text-to-Speech Built-in ✓ ✗ ✗ ✗ ✗ ✗ ✗ ND
Audio transcription Built-in ✓ ✗ ✗ ✗ ✗ ✗ ND ND
Audio translation Built-in ✓ ✗ ✗ ✗ ✗ ✗ ND ND
Non-speech audio Built-in ✓ ✗ ✗ ✗ ✗ ✗ ✗ ND
Video generation Built-in ✓ ✗ ✗ ✗ ✗ ✗ ND ND
AG-UI event mocking Built-in ✓ ✗ ✗ ✗ ✗ ✗ ND ND
MCP tool mocking Built-in ✓ ✗ ✗ partial ✗ ✗ ✓ ND
Scenario-scoped MCP tool fakes ✓ ✗ ✗ ✗ ✗ ✗ ND ND
Fail on undeclared MCP tool ✓ ✗ ✗ ✗ ✗ ✗ ND ND
A2A agent mocking Built-in ✓ ✗ ✗ ✗ ✗ ✓ ✓ ND
Vector DB mocking Built-in ✓ ✗ ✗ ✗ ✗ ✗ ND ND
Search & rerank Built-in ✓ ✗ ✗ ✗ ✗ ✗ partial ND
Record & replay Built-in ✓ ✗ ✗ ✗ ✗ ✗ ✓ ✓ (HTTP)
Drift detection ✓ ✗ ✗ ✗ ✗ ✗ partial ✗
Sequential / stateful responses Built-in ✓ manual ✓ ✓ ✗ ✗ ✓ ✓ (HTTP)
Request journal ✓ manual ✗ ✗ ✓ ✗ ✓ ✓
Error injection ✓ ✓ partial ✗ ✓ ✗ ✓ ✓ (HTTP)
Chaos testing Built-in ✓ ✗ ✓ ✗ ✗ ✗ ✓ HTTP faults and delays
Model misbehavior faults (tool-call JSON, schema, unknown tool, stop reasons) Built-in ✓ ND ND ND Partial
stop-reason controls 		Partial
stop-reason controls
OpenAI / Anthropic 		Partial ND
Streaming physics Built-in ✓ ✗ ✓ ✗ ✗ ✗ ✓ partial
Structured output / JSON mode Built-in ✓ manual ✓ ✗ ✗ ✗ ✓ ND
Programmatic API ✓ (TypeScript/JS) ✓ (TypeScript/JS) No (binary only) ✗ ✗ ✓ (Kotlin/JVM) ✓ (8 languages) ✓ (Java/JVM)
Fixture files JSON ✓ Code-only Tera templates YAML config JSON templates ✗ ✓ (JSON) ✓ (JSON)
GitHub Action Built-in ✓ ✗ ✗ ✗ ✓ ✓ ✓ ND
Vitest / Jest plugins Built-in ✓ ✗ ✗ ✗ ✗ ✗ partial ND
Docker + Helm Both ✓ ✗ Docker only ✓ (Both) Docker only ✗ ✓ ✓ (Helm experimental)
Prometheus metrics Built-in ✓ ✗ ✓ ✗ ✗ ✗ ✓ partial
Streaming usage chunks Built-in ✓ ✗ ✓ ✗ ✗ ✗ partial ND
Rate limiting headers Built-in ✓ ✗ ✗ ✗ partial ✗ partial ND
Native model catalogs (Anthropic, Gemini) Built-in ✓
1.46.0+ 		✗ OpenAI format only OpenAI format only ✗ ✗ ✗ ND
Token-count endpoints Built-in ✓
1.46.0+ 		✗ Gemini only (fixed count) ✗ ✗ ✗ ✗ ND
Native 401 auth errors Opt-in ✓
1.46.0+ 		manual ✓ manual partial manual partial manual
Dependencies Zero ✓ ~300KB Zero (Rust) Node+Express Minimal JVM (Kotlin) JVM, or JVM-less binary JVM

supported · partial · manual · not supported · ND not documented

Agent tool mocking

Requires 1.45.0+

Capability aimock MCP fakes Mastra Experiment Tool Mocks MockServer MCP mocking
Works with any agent framework ✓ (over MCP HTTP) ✗ ✓ (over MCP HTTP)
MCP tools ✓ ND ✓
In-process (non-network) tools ✗ (runs out of process by design) ✓ n/a
Ordered answers per tool ✓ ✓ ND
Exact-argument matching ✓ ✓ ND
Any-argument matching ✓ ✓ ✓ (one answer for every call)
Fail on undeclared tool ✓ ✓ ND
Scripted tool errors ✓ ND ✓
Per-test state and reset ✓ ✓ ND
LLM responses mocked in the same scenario ✓ ND partial
Create fakes from recorded runs ✓ (record live MCP, replay offline) partial ✓
Report unused mocks ✓ (per test; can fail the test) ✓ ND
Workflow / multi-step pipeline targets ✓ (any caller over MCP HTTP) Planned ✓ (any caller over MCP HTTP)

supported · partial · not supported · ND not documented

Ready to switch? We got you.

Step-by-step migration guides for the mock tools below.

MSW VidaiMock mock-llm piyook Python Mokksy openai-responses

Built for production

AG-UI uses aimock for its end-to-end test suite, verifying AI agent behavior across LLM providers with fixture-driven responses in the codebase. Browse the example fixtures to get started.

copilotkit.dev / vscode aimock oversight pathfinder outpost