How to Mock MCP Servers for Agent Testing

How to implement mocking mcp servers for testing reliably

Building reliable AI agents requires rigorous testing, but testing against live Model Context Protocol (MCP) servers creates problems. Live servers are often slow, expensive to query, and difficult to force into specific error states. Relying on them for validation makes tests fail unpredictably due to network hiccups or API rate limits.

Mocking MCP servers is the solution. By simulating the server's responses, you control the data your agent receives. This allows you to test how your agent handles unexpected tool outputs, latency, and protocol errors without making a network call.

According to industry standards, fixing bugs in production is exponentially more expensive than catching them during development. Mocking moves this detection earlier, allowing you to catch errors in your agent's logic before they reach a live environment.

Helpful references: Fast.io Workspaces, Fast.io Collaboration, and Fast.io AI.

What to check before scaling mocking mcp servers for testing

To mock an MCP server, you must understand how the protocol transmits data. MCP uses a client-server architecture where messages are exchanged via a transport layer. This is usually stdio (standard input/output) for local processes or SSE (Server-Sent Events) for remote HTTP connections.

When an agent "calls a tool," it sends a JSON-RPC request over this transport. The server processes the request and sends back a JSON-RPC response.

Key Mocking Strategy: Instead of launching a full server process, you can intercept these JSON-RPC messages at the transport layer. By replacing the real transport with a mock implementation, you can return set responses immediately for any tool call and simulate different situations your agent might encounter.

3 Ways to Mock MCP Servers

There are three primary approaches to mocking MCP servers, ranging from simple scripts to dedicated testing libraries.

1. The "Echo" Mock Script

For simple integration tests, you can create a basic script (in Python or Node.js) that listens on stdio and returns canned responses. This "stub" server implements just enough of the MCP protocol to complete a handshake and respond to specific tool calls. It's lightweight and works well for verifying that your client can successfully initiate a connection.

2. Mocking the Transport Layer (Unit Testing)

The best method for unit testing is to mock the transport class within your agent's code. If you are using the MCP SDK, you can inject a MockTransport instead of a real StdioServerTransport. This allows your test suite to inspect outgoing requests and inject responses directly into the agent's event loop, enabling fast tests with zero external dependencies.

3. Using Dedicated Mocking Tools

Tools like mcpmock and rhitune2 help make this easier. These libraries provide pre-built mock servers that you can configure with a schema. You define the tools and their expected outputs in a JSON file, and the mock server handles the protocol details. This is good for teams that want to standardize their testing infrastructure without writing custom transport mocks.

Step-by-Step: Implementing a Mock Transport

Implementing a custom mock transport gives you complete control over your test scenarios. Here is a conceptual example of how to structure a mock transport in TypeScript using the MCP SDK interfaces.

1. Define the Mock Transport Class Create a class that implements the Transport interface. Instead of writing to a stream, it will push messages to an internal queue or handle them immediately.

class MockTransport implements Transport {
  private responseMap: Map<string, any>;

constructor(responses: Record<string, any>) {
    this.responseMap = new Map(Object.entries(responses));
  }

async start(): Promise<void> {
    // Simulate connection startup
    console.log("Mock transport started");
  }

async send(request: JSONRPCRequest): Promise<void> {
    // Check if it's a tool call
    if (request.method === "tools/call") {
       const toolName = request.params.name;
       const mockResponse = this.responseMap.get(toolName);

if (mockResponse) {
         // Simulate success response
         this.receive({
           jsonrpc: "2.0",
           id: request.id,
           result: mockResponse
         });
       } else {
         // Simulate error
         this.receive({
           jsonrpc: "2.0",
           id: request.id,
           error: { code: -32601, message: "Tool not found" }
         });
       }
    }
  }
}

2. Injecting the Mock When initializing your MCP client in a test, pass this MockTransport instead of the real StdioServerTransport.

const mockResponses = {
  "calculate_tax": { content: [{ type: "text", text: "Tax: $15.00" }] }
};
const client = new Client(new MockTransport(mockResponses));
await client.connect();

This pattern allows you to define exactly what the "server" returns for any given test case, ensuring your tests are deterministic and fast.

Advanced Mocking: Simulating Complex Interactions

Simple request-response mocks are great for unit tests, but real-world agents often need to handle complex, multi-step workflows. Advanced mocking techniques allow you to simulate these richer interactions.

Stateful Mocks

Sometimes a tool call changes the state of the server. For example, a create_user tool should make a subsequent get_user call return the new user. To test this, your mock transport needs an internal state.

• Setup: Initialize the mock with an empty "database" object.
• Action: When create_user is called, update the internal object.
• Verification: When get_user is called, return data from that internal object.

Dynamic Responses

Static JSON responses can't test logic that depends on input parameters. A dynamic mock accepts a callback function instead of a static object.

• Scenario: Testing a date_diff tool.
• Implementation: The mock function receives the start_date and end_date arguments from the request, calculates the difference, and returns the result. This validates that your agent is passing arguments correctly, not just that it can receive a response.

Simulating Asynchronous Events

Real MCP servers might send notifications or progress updates before the final result. You can simulate this by having your mock transport emit notifications/progress messages before sending the final result message. This is critical for testing how your agent UI handles long-running tasks without freezing.

Testing Edge Cases: Errors and Latency

Mocking is most useful for testing what's hard to reproduce with live systems: failure. Agents need to be resilient, and mocks allow you to test that reliability consistently.

Common Scenarios to Mock:

• Protocol Errors: Simulate a malformed JSON-RPC response to ensure your agent doesn't crash.
• Tool Failures: Force a tool to return a "multiple Internal Error" or a specific error code. Does your agent retry the action or ask the user for clarification?
• Latency: Introduce delays in your mock transport to test your agent's timeout settings.
• Hallucinated Parameters: Send valid responses to invalid tool calls to see if the agent can recover from its own mistakes.

From Local Mocks to Live Staging on Fast.io

Once your agent passes its unit tests with mocks, it's time for integration testing in a secure environment.

Fast.io is a good place for this phase.

Fast.io offers a free agent tier that includes 50GB of storage and access to hundreds of pre-built MCP tools. You can deploy your agent to a private workspace, connect it to real (but sandboxed) tools, and watch how it acts safely.

Why Stage on Fast.io?

• Zero Infrastructure: No need to spin up Docker containers or manage server processes.
• Real-World Latency: Test how your agent handles real network conditions.
• Audit Trails: Every tool call and file access is logged, making it easy to debug interaction issues.
• Safe Playground: Use Fast.io's granular permissions to limit what your agent can access during testing.

Frequently Asked Questions

What is an MCP mock server? An MCP mock server is a simulation of a real MCP server. It intercepts tool calls and returns pre-defined responses, allowing developers to test agent behavior without connecting to a live backend.

Can I use standard unit test libraries like Jest or Pytest? Yes. By mocking the MCP transport layer, you can use standard assertion libraries to verify that your agent sent the correct tool calls and handled responses correctly.

How do I test MCP tools that require authentication? Mock the authentication handshake in your test setup. Your mock transport should accept the initialization request and return a success response, simulating a valid session without requiring real credentials.

Why should I mock instead of using a dev server? Mocks are faster, more reliable, and allow you to simulate edge cases (like network failures) that are difficult to reproduce with a real server. They also reduce costs by avoiding API usage fees during the testing phase.