Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt

Use this file to discover all available pages before exploring further.

The MCP interceptor system allows you to mock tool responses, modify requests, and simulate various conditions without calling the actual server implementation.

​
When to Use Mocking

Use MCP-level mocking when you want to:
  • Skip expensive tool operations in tests
  • Simulate error conditions
  • Test client behavior without server dependencies
  • Add latency to test timeout handling
  • Verify request parameters without side effects
For mocking external HTTP calls made by your tools, use HTTP Mocking instead.

​
Mock Registry

The mcp.mock API provides a registry for mocking MCP responses.

​
Basic Usage

import { mockResponse } from '@frontmcp/testing';

test('mock tool response', async ({ mcp }) => {
  // Register a mock
  const handle = mcp.mock.add({
    method: 'tools/call',
    params: { name: 'expensive-tool' },
    response: mockResponse.toolResult([
      { type: 'text', text: JSON.stringify({ result: 'mocked' }) },
    ]),
  });

  // Call the tool - gets mocked response
  const result = await mcp.tools.call('expensive-tool', { data: 'test' });
  expect(result.json()).toEqual({ result: 'mocked' });

  // Check mock was used
  expect(handle.callCount()).toBe(1);

  // Clean up
  handle.remove();
});

​
Mock Options

OptionTypeDescription
methodstringMCP method to match (e.g., 'tools/call')
paramsobjectParameters to match (partial match)
responseobjectJSON-RPC response to return
timesnumberNumber of times to use this mock (default: unlimited)
delaynumberDelay in ms before responding

​
Convenience Methods

​
Mocking Tools

test('mock tool with convenience method', async ({ mcp }) => {
  // Mock a successful tool response
  mcp.mock.tool('my-tool', { success: true, data: 'mocked' });

  const result = await mcp.tools.call('my-tool', { input: 'test' });
  expect(result).toBeSuccessful();
  expect(result.json()).toEqual({ success: true, data: 'mocked' });
});

test('mock tool error', async ({ mcp }) => {
  // Mock a tool error
  mcp.mock.toolError('failing-tool', -32603, 'Simulated failure');

  const result = await mcp.tools.call('failing-tool', {});
  expect(result).toBeError(-32603);
});

​
Mocking Resources

test('mock resource', async ({ mcp }) => {
  // Mock with string content
  mcp.mock.resource('config://settings', 'mock config data');

  // Mock with structured content
  mcp.mock.resource('data://users', {
    text: JSON.stringify([{ id: 1, name: 'Mock User' }]),
    mimeType: 'application/json',
  });

  const content = await mcp.resources.read('config://settings');
  expect(content.text()).toBe('mock config data');
});

​
Clearing Mocks

test('clear mocks', async ({ mcp }) => {
  mcp.mock.tool('tool-1', { data: 'mock1' });
  mcp.mock.tool('tool-2', { data: 'mock2' });

  // Clear all mocks
  mcp.mock.clear();

  // Now calls go to actual server
  const result = await mcp.tools.call('tool-1', {});
  // ... actual response
});

​
Request Interceptors

Intercept and modify outgoing requests before they reach the server.

​
Logging Requests

test('log all requests', async ({ mcp }) => {
  const requests: any[] = [];

  mcp.intercept.request((ctx) => {
    requests.push({
      method: ctx.request.method,
      params: ctx.request.params,
    });
    return { action: 'passthrough' };
  });

  await mcp.tools.list();
  await mcp.tools.call('my-tool', { input: 'test' });

  expect(requests).toHaveLength(2);
  expect(requests[0].method).toBe('tools/list');
});

​
Modifying Requests

test('inject params into requests', async ({ mcp }) => {
  mcp.intercept.request((ctx) => {
    if (ctx.request.method === 'tools/call') {
      return {
        action: 'modify',
        request: {
          ...ctx.request,
          params: {
            ...ctx.request.params,
            arguments: {
              ...ctx.request.params.arguments,
              injectedParam: 'test-value',
            },
          },
        },
      };
    }
    return { action: 'passthrough' };
  });

  // Request will include injectedParam
  await mcp.tools.call('my-tool', { input: 'test' });
});

​
Returning Mock Response

test('return mock from interceptor', async ({ mcp }) => {
  mcp.intercept.request((ctx) => {
    if (ctx.request.method === 'tools/list') {
      return {
        action: 'mock',
        response: {
          jsonrpc: '2.0',
          id: ctx.request.id,
          result: { tools: [{ name: 'fake-tool' }] },
        },
      };
    }
    return { action: 'passthrough' };
  });

  const tools = await mcp.tools.list();
  expect(tools).toHaveLength(1);
  expect(tools[0].name).toBe('fake-tool');
});

​
Failing Requests

test('fail specific requests', async ({ mcp }) => {
  mcp.intercept.request((ctx) => {
    if (ctx.meta.sessionId === undefined) {
      return {
        action: 'error',
        error: new Error('Session required'),
      };
    }
    return { action: 'passthrough' };
  });
});

​
Interceptor Actions

ActionDescription
passthroughContinue to server normally
modifyModify the request before sending
mockReturn a mock response without calling server
errorThrow an error

​
Response Interceptors

Intercept and modify responses after they’re received from the server.

​
Logging Responses

test('log response times', async ({ mcp }) => {
  const timings: { method: string; duration: number }[] = [];

  mcp.intercept.response((ctx) => {
    timings.push({
      method: ctx.request.method,
      duration: ctx.durationMs,
    });
    return { action: 'passthrough' };
  });

  await mcp.tools.list();
  await mcp.tools.call('my-tool', {});

  console.log('Request timings:', timings);
});

​
Modifying Responses

test('add extra tool to list', async ({ mcp }) => {
  mcp.intercept.response((ctx) => {
    if (ctx.request.method === 'tools/list') {
      const tools = ctx.response.result.tools || [];
      return {
        action: 'modify',
        response: {
          ...ctx.response,
          result: {
            tools: [
              ...tools,
              { name: 'injected-tool', description: 'Added by interceptor' },
            ],
          },
        },
      };
    }
    return { action: 'passthrough' };
  });

  const tools = await mcp.tools.list();
  expect(tools).toContainTool('injected-tool');
});

​
Convenience Helpers

​
Adding Latency

test('simulate slow responses', async ({ mcp }) => {
  // Add 500ms delay to all requests
  const removeDelay = mcp.intercept.delay(500);

  const start = Date.now();
  await mcp.tools.list();
  const duration = Date.now() - start;

  expect(duration).toBeGreaterThanOrEqual(500);

  // Remove the delay
  removeDelay();
});

​
Failing Specific Methods

test('simulate method failure', async ({ mcp }) => {
  // Fail all resources/read calls
  const removeFailure = mcp.intercept.failMethod(
    'resources/read',
    'Simulated storage failure'
  );

  await expect(mcp.resources.read('data://test'))
    .rejects.toThrow('Simulated storage failure');

  // Remove the failure
  removeFailure();

  // Now it works
  const content = await mcp.resources.read('data://test');
  expect(content).toBeDefined();
});

​
Call Tracking

Track how mocks are used: 
test('verify mock calls', async ({ mcp }) => {
  const handle = mcp.mock.tool('tracked-tool', { result: 'mock' });

  // Make multiple calls
  await mcp.tools.call('tracked-tool', { input: 'a' });
  await mcp.tools.call('tracked-tool', { input: 'b' });

  // Check call count
  expect(handle.callCount()).toBe(2);

  // Get all call details
  const calls = handle.calls();
  expect(calls[0].params.arguments.input).toBe('a');
  expect(calls[1].params.arguments.input).toBe('b');
});

​
One-Time Mocks

Create mocks that only match a specific number of times: 
test('simulate intermittent failure', async ({ mcp }) => {
  // First call fails
  mcp.mock.add({
    method: 'tools/call',
    params: { name: 'flaky-tool' },
    response: mockResponse.error(-32603, 'Temporary failure'),
    times: 1,
  });

  // Subsequent calls succeed
  mcp.mock.add({
    method: 'tools/call',
    params: { name: 'flaky-tool' },
    response: mockResponse.toolResult([
      { type: 'text', text: '{"success": true}' },
    ]),
  });

  // First call fails
  const result1 = await mcp.tools.call('flaky-tool', {});
  expect(result1).toBeError();

  // Second call succeeds
  const result2 = await mcp.tools.call('flaky-tool', {});
  expect(result2).toBeSuccessful();
});

​
mockResponse Helpers

Pre-built response creators for common scenarios: 
import { mockResponse } from '@frontmcp/testing';

// Success responses
mockResponse.success({ data: 'result' });
mockResponse.toolResult([{ type: 'text', text: 'Hello' }]);
mockResponse.toolsList([{ name: 'tool1' }, { name: 'tool2' }]);
mockResponse.resourcesList([{ uri: 'file://a', name: 'A' }]);
mockResponse.resourceRead([{ uri: 'file://a', text: 'content' }]);

// Error responses
mockResponse.error(-32603, 'Internal error');
mockResponse.errors.methodNotFound('unknown');
mockResponse.errors.resourceNotFound('file://missing');
mockResponse.errors.invalidParams('Missing required field');
mockResponse.errors.unauthorized();

​
Best Practices

Do:
  • Mock expensive operations (external APIs, database calls)
  • Use times: 1 to test retry logic
  • Clear mocks between tests if needed
  • Use convenience methods for simple cases
Don’t:
  • Mock everything - some tests should hit real code
  • Forget to remove interceptors after tests
  • Use mocking to hide bugs in your code
  • Over-engineer mock setups
// Good: Mock external dependency
mcp.mock.tool('fetch-weather', { temp: 72 });

// Bad: Mock internal logic you should test
mcp.mock.tool('calculate-total', { total: 100 });
// Better: Let calculate-total run and verify its logic