Mock · Proxy · Replay

Mock, proxy & replay any HTTP API

Stand up mock endpoints in seconds, forward to the real service when you're ready, and drive it all from the dashboard — or from Claude over MCP.

Deploy in seconds Learn the concepts

Test today, wire up the real API later

You and QA keep testing against Beo Echo mocks while the backend is still being built — nobody waits. The scene below cycles through the rollout: not ready → partial → real API ready, forwarding endpoints one at a time.

That gradual hand-off is exactly the mock → production path below.

The building blocks

Everything nests. A workspace holds projects; a project holds endpoints; each endpoint holds responses; a response can carry rules.

Workspace

The team boundary.

Project

One mock server.

Endpoint

A route: method + path.

Response

What gets returned.

Rule

Conditional matching.

Workspace

The top-level container. Members, roles, and projects all live inside a workspace, so access is isolated per team.

e.g. one workspace per team — projects and members stay separate.

Project

A single mock server with its own alias (URL) and one operating mode. This is the thing you point your app at.

e.g. "payments-sandbox" → https://host/payments-sandbox

Endpoint

Matches an incoming request by HTTP method and path. Path params like :id are supported for flexible matching.

e.g. POST /v1/users/:id/orders

Response

Status code, body, and headers. An endpoint can hold several responses; mark one as the fallback so it always matches.

e.g. 200 with { "code": 200, "message": "Success" }

Rule

Attach rules to a response to pick it only when the request matches — by header, query, body, or path. Combine with AND / OR.

e.g. return this response only when body plan = "pro"

The three modes (+ off)

A project handles every request one way. Watch where the request goes.

Mock

Serve your responses only

Every request is answered from your configured responses — and you pick exactly which one comes out via rules, priority, or a fallback. The real server is never contacted.

Backend is down or not built yet, or you want fully isolated, deterministic tests.

Proxy

Selective — matched mock stops, rest forwards

match → answered & sent back · no match → forwarded on

Per request, Beo Echo checks your mocks first. If an endpoint matches AND its rules match, that mock answers and the request stops there. Anything without a matching mock is forwarded to the real target.

Partial mocks — stub specific endpoints (or just specific rule cases); let everything else hit the real API.

Forwarder

Always forward, always log

Every request goes straight to the real target — mocks are ignored entirely — while the full traffic is recorded.

Capture and inspect real request/response pairs before you decide what to mock.

Disabled

Inactive

The project serves nothing. Useful to temporarily park a project.

You want to keep the config but stop it responding.

Connect it to Claude (MCP)

One endpoint, three ways to connect. Your endpoint: https://<your-beo-echo-host>/mcp

Claude Code (CLI)

1 Register the streamable-HTTP server.
2 Log in — a browser opens, then click Approve.
3 Confirm it is connected.

claude mcp add --transport http beo-echo https://<your-beo-echo-host>/mcp
claude mcp login beo-echo
claude mcp list

Claude.ai

OAuth — paste the URL, no token

1 Settings → Integrations → Add custom MCP server.
2 Paste the endpoint URL.
3 Log in if prompted, then Approve.

Desktop · Cursor · VS Code

Static bearer token

1 Profile → MCP → Access Tokens → Generate (shown once).
2 Drop the endpoint + token into the client config.
3 Reload the client.

{
  "mcpServers": {
    "beo-echo": {
      "url": "https://<your-beo-echo-host>/mcp",
      "headers": { "Authorization": "Bearer beo_pat_..." }
    }
  }
}

Common use cases

What people actually ask Claude to do, once connected.

Scan an existing project

You inherited a project and want the full picture fast.

"List my projects in this workspace."
"Scan project X — show every endpoint and its responses."
"Which endpoints are still forwarding vs mocked?"

Capture real traffic (Forwarder)

You need real payloads before writing any mock.

Set the project to Forwarder mode, pointing at the real API.
Route your app through it and exercise the flow.
"Show the last 20 logs" — then copy the real responses into mocks.

Stub a flaky endpoint (Proxy)

One endpoint is unreliable; the rest work fine.

Switch the project to Proxy mode.
"Add a mock for POST /payments returning 200 success."
Everything else keeps hitting the real API automatically.

Test with the backend down (Mock)

Staging is dead but you must demo the full flow.

Set the project to Mock mode.
"Mock the whole flow from login to checkout, all 200."
Point BASE_URL at the project — every call succeeds.

From mock to production

You rarely jump straight to a full mock. Grow into it — and back out — one mode at a time.

Forwarder

Observe

Route through Beo Echo to the real/staging API and record real traffic.

Mock

Build

Recreate the endpoints you need as mocks so you can develop in isolation.

Proxy

Blend

Flip to Proxy: keep mocking what is not ready, forward everything that is.

Production

Cut over

As the real API stabilises, drop mocks and point the app straight at production.

Deploy in seconds

Run your own Beo Echo with a single Docker command.

$ docker run -d --platform linux/amd64 -p 8080:80 \
 -v $(pwd)/beo-echo-config:/app/configs/ \
 ghcr.io/yogasw/beo-echo:latest

Run command

In your terminal.

Open browser

at localhost:8080

Log in & start

admin@admin.com / admin

Database options

• Default: SQLite (auto-created)
• PostgreSQL: set DATABASE_URL

Configuration

• Config in ./beo-echo-config/
• Persistent data across restarts