Beeceptor MCP

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 the following 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

Beeceptor MCP works in both Claude Code and Claude Desktop. The configuration differs.

Claude Code (IDE)

Claude Code can connect to Beeceptor’s MCP server over HTTP.

claude mcp add --transport http beeceptor 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.

Claude Desktop

Claude Desktop runs MCP servers in a local process and typically uses a bridge like mcp-remote. Add Beeceptor under mcpServers in your Claude Desktop config (e.g. claude_desktop_config.json) with command and args:

"beeceptor": {
  "command": "npx",
  "args": [
    "mcp-remote",
    "https://mcp.beeceptor.com/mcp",
    "--header",
    "Authorization: Bearer <TOKEN>",
    "--header",
    "endpoint: <ENDPOINT_NAME>"
  ]
}

Replace <TOKEN> and <ENDPOINT_NAME> with your API key and 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.
• MCP server fails to load in Claude Desktop (ReferenceError: File is not defined or npm WARN EBADENGINE (requires Node >= 20)): This usually means a Node.js version mismatch. Claude Desktop runs MCP servers in a non-login shell that does not load nvm, so it may use an older system Node (e.g. Node 18) even if your terminal uses Node 20+. Tools like mcp-remote need a newer Node and can crash on older runtimes.
  Fix: Point Claude Desktop at the correct Node by using absolute paths and overriding PATH. Instead of "command": "npx", use the full path to your Node binary and run npx via its CLI script, with the correct Node’s bin directory first in PATH. That way Claude Desktop uses the same Node as your terminal and the server should load.
  If it still fails, contact Beeceptor support for help.