MCPMock

Mock MCP (Model Context Protocol) server for testing tool integrations. Implements the Streamable HTTP transport with JSON-RPC dispatch, session management, and full tools/resources/prompts support.

Quick Start

Standalone mode typescript 
import { MCPMock } from "@copilotkit/aimock";

const mcp = new MCPMock();

mcp.addTool({ name: "search", description: "Search the web" });
mcp.onToolCall("search", (args) => {
  return `Results for: ${(args as { query: string }).query}`;
});

const url = await mcp.start();
// Point your MCP client at `url`

Mounted Mode

Mount MCPMock onto an LLMock server to share a single port with LLM mocking and other services:

Mount on LLMock typescript 
import { LLMock, MCPMock } from "@copilotkit/aimock";

const llm = new LLMock({ port: 5555 });
const mcp = new MCPMock();

mcp.addTool({ name: "calc", description: "Calculator" });
mcp.onToolCall("calc", (args) => "42");

llm.mount("/mcp", mcp);
await llm.start();
// MCP available at http://127.0.0.1:5555/mcp

Subpath Import

MCPMock is also available via a dedicated subpath import for tree-shaking:

Subpath import typescript 
import { MCPMock } from "@copilotkit/aimock/mcp";

Tools

Register tools and their handlers:

Tools API typescript
// Register a tool definition
mcp.addTool({
  name: "search",
  description: "Search the web",
  inputSchema: { type: "object", properties: { query: { type: "string" } } },
});

// Register a handler (returns string or MCPContent[])
mcp.onToolCall("search", (args) => {
  const { query } = args as { query: string };
  return `Found 3 results for "${query}"`;
});

// Or return rich content
mcp.onToolCall("rich-tool", () => [
  { type: "text", text: "Hello" },
  { type: "image", data: "base64...", mimeType: "image/png" },
]);

Resources

Register static resources that clients can read:

Resources API typescript 
mcp.addResource(
  { uri: "file:///readme.md", name: "README", mimeType: "text/markdown" },
  { text: "# My Project\nWelcome!" },
);

Prompts

Register prompt templates with optional handlers:

Prompts API typescript
mcp.addPrompt(
  { name: "summarize", arguments: [{ name: "text", required: true }] },
  (args) => ({
    messages: [
      { role: "user", content: { type: "text", text: `Summarize: ${(args as { text: string }).text}` } },
    ],
  }),
);

Config File

MCPMock can be configured via the aimock JSON config file:

aimock.json json
{
  "mcp": {
    "path": "/mcp",
    "tools": [
      { "name": "search", "description": "Search", "result": "Found it" }
    ],
    "resources": [
      { "uri": "file:///data.json", "name": "Data", "text": "{\"key\": \"value\"}" }
    ]
  }
}

Session Management

MCPMock implements full session management per the MCP Streamable HTTP spec. Each initialize request creates a new session, and the session ID is returned via the Mcp-Session-Id header. All subsequent requests must include this header.

Method Description
initialize Creates session, returns capabilities and session ID
tools/list Lists all registered tools
tools/call Calls a tool by name with arguments
resources/list Lists all registered resources
resources/read Reads a resource by URI
prompts/list Lists all registered prompts
prompts/get Gets a prompt by name with arguments
ping Returns empty object (health check)
DELETE / Destroys a session

Inspection

Inspection API typescript 
mcp.health();       // { status: "ok", tools: 2, resources: 1, prompts: 0, sessions: 1 }
mcp.getSessions();  // Map of active sessions
mcp.getRequests();  // Journal entries (when mounted with shared journal)
mcp.reset();        // Clears all tools, resources, prompts, and sessions