mcp-explorer

A controllable, observable MCP server. It speaks the Model Context Protocol to real MCP clients (Claude, MCP Inspector, your own client), but its behavior is driven entirely at runtime by you over a REST API + SSE stream:

Dynamically set the tools exposed to a given MCP client — per session, with a global default. Changing a session's tools pushes tools/list_changed so the client re-fetches.
Observe tool calls in real time and set the response before it returns — either from a preset (canned response, optional simulated latency/errors) or a live human-in-the-loop reply while the call blocks.

Useful as a mock / MITM harness for testing how MCP clients behave against arbitrary tool sets and arbitrary responses, without writing a bespoke server.

Architecture

              ┌──────────────────────── FastAPI app ────────────────────────┐
 MCP client ──┤  /mcp         Streamable HTTP (stateful)  → low-level Server  │
 (Inspector)  │  /api/*       REST control plane           → SessionRegistry  │
              │  /api/events  SSE event stream             → EventBus         │
              └──────────────────────────────────────────────────────────────┘
 controller ──(REST: set tools, respond)──┘        controller ──(SSE: watch)──┘

Sessions are distinguished by the Mcp-Session-Id the server assigns on initialize (stateful Streamable HTTP). All state is in-memory in one process.
Built on the MCP Python SDK v2 low-level Server (arbitrary JSON-schema tools, per-session tool lists) — see src/mcp_explorer/mcp_server.py.

Run

uv run mcp-explorer            # serves on http://127.0.0.1:8000

Config via env vars: MCP_EXPLORER_HOST, MCP_EXPLORER_PORT, MCP_EXPLORER_TIMEOUT_S (live-response timeout, default 300s), MCP_EXPLORER_MODE (manual | auto), MCP_EXPLORER_API_TOKEN (optional bearer token guarding /api/*).

MCP endpoint: http://127.0.0.1:8000/mcp
REST + SSE: http://127.0.0.1:8000/api/... (OpenAPI docs at /docs)
Web dashboard: http://127.0.0.1:8000/live

Web dashboard

Open http://127.0.0.1:8000/live for a dependency-free (vanilla HTML/CSS/JS) dashboard that uses the REST + SSE APIs: watch the live event stream, see connected sessions (each gets a friendly auto-assigned adjective-animal name, which you can override), edit the tool set (global or per-session), toggle a session's mode, set presets, and answer blocked tool calls inline.

The UI is fully stream-driven — it does not poll. It fetches state once on load, then updates reactively from the SSE stream: pending-call counts come straight from tool-call events, and structural changes (a session connecting, or tools/mode/preset changes — the latter emit a session_updated event) trigger a single authoritative resync. It also resyncs whenever the EventSource reconnects. Because browsers can't attach headers to an EventSource, the live stream assumes MCP_EXPLORER_API_TOKEN is unset (the default).

Quick start

# 1. start the server
uv run mcp-explorer

# 2. define a default tool set
uv run python examples/set_tools.py

# 3. connect a client, e.g. the MCP Inspector
npx @modelcontextprotocol/inspector    # point it at http://127.0.0.1:8000/mcp

# 4. watch calls and answer them live
uv run python examples/respond_live.py

Interception modes

Each session has a mode (default from MCP_EXPLORER_MODE):

manual — a tool call blocks until either a matching preset exists or you POST a live response; if neither arrives within the timeout it returns an error.
auto — a call with a preset returns it immediately; a call without a preset returns a fast "no preset configured" error instead of blocking.

Presets always take precedence over blocking, in either mode.

REST API

Method & path	Purpose
`GET /api/healthz`	Liveness.
`GET /api/sessions`	List active sessions.
`GET /api/sessions/{sid}`	Session detail.
`PUT /api/sessions/{sid}/name`	Rename a session (human-readable label).
`PUT /api/tools`	Set the global default tool set.
`PUT /api/sessions/{sid}/tools`	Set tools for one session (→ `list_changed`).
`DELETE /api/sessions/{sid}/tools`	Revert a session to the default tool set.
`PUT /api/sessions/{sid}/mode`	Set `manual` / `auto`.
`PUT /api/sessions/{sid}/tools/{name}/preset`	Set/replace a preset response.
`DELETE /api/sessions/{sid}/tools/{name}/preset`	Remove a preset.
`GET /api/sessions/{sid}/pending`	Calls currently awaiting a response.
`POST /api/calls/{call_id}/respond`	Resolve a blocked call with a live payload.
`GET /api/events`	SSE stream (optional `?session_id=` filter).

Tool definitions (ToolDef) carry a raw JSON Schema in input_schema, so you can expose any tool shape. Responses (PresetResponse / live RespondPayload) accept text (single text block) or content (list of MCP content blocks), structured_content, and is_error; presets also accept delay_s.

Events

SSE emits: session_created, session_closed, tools_updated, tool_call_started, tool_call_awaiting_response, tool_call_completed, tool_call_timeout — each with type, session_id, timestamp, and data.

Tests

uv run pytest

tests/test_end_to_end.py boots a real server and drives it with a real MCP client to exercise dynamic tools, live interception, presets, and timeouts.

Notes / limitations

Single-process, in-memory state. Horizontal scaling would need shared state + sticky sessions (out of scope).
tools/list_changed requires the client to hold its stream open; modern protocol clients (e.g. the Inspector) do.