MCP Servers — Mimic Docs

MCP Servers — Overview

Every API mock adapter has a corresponding MCP server. MCP servers translate MCP tool calls into HTTP requests against the Mimic mock server.

textdata flow

AI Agent  —MCP—>  Mimic MCP Server  —HTTP—>  Mimic Mock Adapter
(Claude)           (adapter-stripe)              (Stripe mock routes)

This matters because many agent frameworks use MCP as their primary tool interface. Mimic MCP servers give agents realistic mock data through the same protocol they’ll use in production.

MCP Setup & Config

With Claude Code

bash

$ claude mcp add mimic-stripe -- npx -y @mimicai/adapter-stripe mcp

# With custom URL
$ claude mcp add --env MIMIC_BASE_URL=http://localhost:4100 mimic-stripe -- npx -y @mimicai/adapter-stripe mcp

With Cursor / VS Code

jsonMCP config

{
  "mcpServers": {
    "mimic-stripe": {
      "command": "npx",
      "args": ["-y", "@mimicai/adapter-stripe", "mcp"],
      "env": { "MIMIC_BASE_URL": "http://localhost:4100" }
    },
    "mimic-plaid": {
      "command": "npx",
      "args": ["-y", "@mimicai/adapter-plaid", "mcp"],
      "env": { "MIMIC_BASE_URL": "http://localhost:4100" }
    }
  }
}

With Mimic CLI

The simplest way — configure adapters in mimic.json with mcp: true and mimic host starts everything together:

jsonmimic.json

{
  "apis": {
    "stripe": { "enabled": true, "mcp": true },
    "plaid": { "enabled": true, "mcp": true }
  }
}

bash

$ mimic host

✓ Stripe API    → http://localhost:4101/stripe/v1
✓ Stripe MCP    → http://localhost:4201/mcp
✓ Plaid API     → http://localhost:4102/plaid
✓ Plaid MCP     → http://localhost:4202/mcp
✓ Ready in 1.4s

Available MCP Servers

All 9 shipped adapters include a full MCP server. Each can be run standalone via npx or started together via mimic host.

Adapter	Package	Standalone MCP Command	Status
Stripe	`@mimicai/adapter-stripe`	`npx @mimicai/adapter-stripe mcp`	Shipped
Plaid	`@mimicai/adapter-plaid`	`npx @mimicai/adapter-plaid mcp`	Shipped
Paddle	`@mimicai/adapter-paddle`	`npx @mimicai/adapter-paddle mcp`	Shipped
Chargebee	`@mimicai/adapter-chargebee`	`npx @mimicai/adapter-chargebee mcp`	Shipped
GoCardless	`@mimicai/adapter-gocardless`	`npx @mimicai/adapter-gocardless mcp`	Shipped
Lemon Squeezy	`@mimicai/adapter-lemonsqueezy`	`npx @mimicai/adapter-lemonsqueezy mcp`	Shipped
Recurly	`@mimicai/adapter-recurly`	`npx @mimicai/adapter-recurly mcp`	Shipped
RevenueCat	`@mimicai/adapter-revenuecat`	`npx @mimicai/adapter-revenuecat mcp`	Shipped
Zuora	`@mimicai/adapter-zuora`	`npx @mimicai/adapter-zuora mcp`	Shipped

Official Parity

Mimic MCP tools are designed to match the official MCP servers published by each platform — same tool names, same parameter shapes, same return format. The goal is zero code changes when you swap a Mimic MCP server for the real one.

Adapter	Based on	Coverage
Stripe	mcp.stripe.com official server	All 26 official tools + 4 Mimic extras for payment lifecycle testing
Plaid	Plaid API surface	Link flow, accounts, transactions, balances, identity, auth, holdings, liabilities
Paddle	Paddle Billing API	Products, prices, subscriptions, customers, transactions, discounts
Chargebee	Chargebee API	Subscriptions, customers, invoices, plans, addons, events
GoCardless	GoCardless API	Mandates, payments, customers, bank accounts, payouts, events
Lemon Squeezy	Lemon Squeezy API	Products, variants, orders, subscriptions, customers, discounts
Recurly	Recurly API	Accounts, subscriptions, invoices, plans, add-ons, transactions
RevenueCat	RevenueCat API	Subscribers, entitlements, offerings, purchases, events
Zuora	Zuora API	Accounts, subscriptions, orders, invoices, payments, products

Zero migration cost: Agent code that calls mimic-stripe MCP tools works unchanged against the real Stripe MCP server in production — no renames, no schema changes.

Environment Variables

Variable	Applies to	Description	Default
`MIMIC_BASE_URL`	Standalone binary only	URL of the mock API server the standalone MCP binary will call	`http://localhost:4100`

MIMIC_BASE_URL is only for standalone binary mode. When you run npx @mimicai/adapter-stripe mcp directly, it needs to know where your mock API server is listening. mimic host does not use this variable — it assigns ports internally and wires each MCP server to its own API server automatically.

Build an MCP Server

Each adapter’s MCP implementation lives in src/mcp.ts. The pattern is a registerMyPlatformTools function (used by both mimic host and the standalone binary) plus a startMyPlatformMcpServer function for the standalone path. A thin src/bin/mcp.ts entry point calls the start function.

typescriptsrc/mcp.ts

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

// Register tools on any McpServer instance — used by mimic host and standalone mode.
export function registerMyPlatformTools(server: McpServer, baseUrl: string): void {
  server.tool(
    'list_items',
    'List all items in the account.',
    {},
    async () => {
      const res = await fetch(`${baseUrl}/my-platform/items`);
      const data = await res.json();
      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
    }
  );

  server.tool(
    'create_item',
    'Create a new item. Requires title. Optionally set priority.',
    {
      title: z.string().describe('Item title'),
      priority: z.enum(['low', 'medium', 'high']).optional(),
    },
    async (params) => {
      const res = await fetch(`${baseUrl}/my-platform/items`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(params),
      });
      const data = await res.json();
      return { content: [{ type: 'text', text: `Created item ${data.id}` }] };
    }
  );
}

// Standalone entry — called by src/bin/mcp.ts.
export async function startMyPlatformMcpServer(): Promise<void> {
  const baseUrl = process.env.MIMIC_BASE_URL ?? 'http://localhost:4100';
  const server = new McpServer({ name: 'mimic-my-platform', version: '0.1.0' });
  registerMyPlatformTools(server, baseUrl);
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

typescriptsrc/bin/mcp.ts

#!/usr/bin/env node
import { startMyPlatformMcpServer } from '../mcp.js';
startMyPlatformMcpServer().catch(console.error);

The registerMyPlatformTools function is also what you pass to registerMcpTools in your adapter class — so mimic host can mount the same tools on its shared MCP server without spawning a separate process.

Tool design tip: Name tools to match the platform's vocabulary. Write descriptions for LLMs, not humans. Return human-readable summaries for write operations, full JSON for reads.

Troubleshooting

“Connection refused” — Ensure mimic host is running before connecting MCP servers
Tools not appearing — Restart your MCP client after adding a new server
Wrong data — MCP servers call the mock HTTP endpoints; lazy seeding happens on first request