Skip to main content

Build Test Doubles directly from IDE with AI

When you're building integrations or testing APIs, creating and updating mock servers manually slows you down. You switch tabs, edit rules, save changes, test again, and repeat.

Beeceptor MCP changes that workflow.

With MCP (Model Context Protocol), AI assistants like Claude or Cursor can directly create and manage your Beeceptor endpoint. You describe what you want. The AI executes structured actions. You see rules appear instantly on the dashboard.

info

Agentic Mode is available on the Team plan and above, as it requires an API key to securely manage and configure the Beeceptor endpoint.

What is MCP?​

MCP stands for Model Context Protocol. It is a standard that allows AI assistants to call real tools instead of only generating text.

In Beeceptor, this means your AI can:

  • Create or update mock rules
  • Inspect request history
  • Configure endpoint settings
  • Manage state data/variables
  • Generate stateful CRUD routes

This is different from asking AI to "write mock JSON." The Beeceptor MCP lets your assistant build a test double / virtual API servers. You stay in your IDE/editor, and see the mock server updates in real time.

How MCP Agentic Mode Works​

Here is what happens when you give an instruction:

  1. You ask Claude or Cursor to configure a mock API, or need an endpoint for HTTP/webhook debugging.
  2. The AI translates your request into MCP tool calls.
  3. Beeceptor executes those tool calls.
  4. The Beeceptor dashboard updates instantly.
  5. You can test the endpoint immediately.

The AI becomes the control layer. Beeceptor remains the execution engine.

Tools and capabilities​

Beeceptor provides structured tools the AI can call. Each tool performs a specific operation.

  • Know your endpoint: Returns your endpoint name and base mock URL.
  • Manage rules: List rules, inspect one rule, create/update/remove rules, replace all rules in one shot, and reorder priority.
  • Advanced behavior rules: Create and manage scenarios for chaos simulation, network latencies, HTTP callout behavior, and CRUD routes.
  • Inspect request history: Search logs with filters, open full request details, or delete/purge history when needed.
  • Manage state data: Store and retrieve key-value data, counters, and lists for stateful mocks.
  • Read/update endpoint settings: Control CORS, security, rate limits, locale, proxy settings, and more.
  • Template helper reference: Fetch Beeceptor's template syntax for dynamic response payloads.
  • OpenAPI reference: Returns Beeceptor's Management API docs and OpenAPI spec.

Demo & Examples​

Creating OAuth server​

Watch this short demo of Beeceptor MCP Agentic Mode in action and see how AI directly controls your mock server in real time.

In this video, Claude receives a natural language instruction to set up an OAuth mock server. You will see MCP tool calls being executed behind the scenes as Beeceptor creates rules for /oauth/authorize, /oauth/token, and /oauth/userinfo, etc. The dashboard updates instantly as dynamic responses are configured. The OAuth endpoints can be tested immediately.

Example prompts​

Try these prompts in your MCP-enabled AI client:

  1. Turn my bug report into a reproducible mock: create a POST /checkout rule that returns 500 when paymentMethod=amex and 200 otherwise.
  2. Simulate an expired OAuth token: modify /oauth/token to return invalid_grant if code=expired123.
  3. Reproduce yesterday’s production issue: create a 3-second delayed response on GET /inventory with 20% failure rate.`
  4. Generate a CRUD API for /api/orders with insert 10 records with order IDs and future delivery dates.
  5. Create a retry scenario: first call to POST /payment returns 500, second call succeeds with 200.

Setup​

To get started you need to get the Bearer token from API Keys in the Beeceptor dashboard. Use that value for the Authorization: Bearer <TOKEN> header.

Setup for Cursor​

Add this follwing to your Cursor MCP settings:

{
  "mcpServers": {
    "beeceptor": {
      "url": "https://mcp.beeceptor.com/mcp",
      "headers": {
        "Authorization": "Bearer <TOKEN>",
        "endpoint": "<ENDPOINT_NAME>"
      }
    }
  }
}

That is it. Cursor can now manage your endpoint.

Setup for Claude​

Via CLI​

Add the Beeceptor MCP server with:

claude mcp add beeceptor -t http --url https://mcp.beeceptor.com/mcp --header "Authorization: Bearer <TOKEN>" --header "endpoint: <ENDPOINT_NAME>"

Then set the Authorization and endpoint headers for beeceptor in your Claude MCP config as needed.

Via config​

In Claude's MCP server configuration, add Beeceptor with URL and headers:

Claude stores MCP servers in a config file (e.g. claude_desktop_config.json or your IDE’s MCP settings). Add a beeceptor entry under mcpServers with the MCP endpoint URL and the required headers so Claude can authenticate and target your endpoint.

{
  "mcpServers": {
    "beeceptor": {
      "transport": "http",
      "url": "https://mcp.beeceptor.com/mcp",
      "headers": {
        "Authorization": "Bearer <TOKEN>",
        "endpoint": "<ENDPOINT_NAME>"
      }
    }
  }
}

Troubleshooting​

  • Missing Authorization: Bearer <token>: Add a Bearer token in MCP headers. Get the token from API Keys in the Beeceptor dashboard.
  • Missing endpoint: Add the endpoint header in MCP config.