Related Pages

Related topics: System Architecture and Data Pipeline, Dashboard, Replay, and Common Operations

Introduction and Quickstart

mcptail is a record-and-replay proxy for Model Context Protocol (MCP) servers. It sits between an MCP client (such as Claude Code, Cursor, or Windsurf) and the underlying stdio MCP servers, capturing every JSON-RPC message exchanged while staying a transparent transport. The goal is to give developers an inspectable timeline of tool calls, an offline replay harness for testing, and a foundation for downstream exporters (HAR, OpenTelemetry, regression-test specs) without changing how the client or server behave on the hot path. Source: README.md:1-40

The project is published as mcptail on npm and currently tracks the v0.1.0 release line. v0.1 is scoped to stdio servers only; Streamable HTTP / SSE transport capture is on the roadmap and tracked separately. Source: ROADMAP.md:1-30

What mcptail does

At runtime, mcptail performs four jobs:

1. Adapter rewrite — rewrites a host's MCP config (e.g. Claude Desktop's claude_desktop_config.json, Cursor's mcp.json, Windsurf's mcp_config.json) so the command field points at mcptail tap <original-command>. The original server still runs unchanged; mcptail is just a wrapper in the middle. Source: src/adapters/index.ts:1-80
2. Line tap — frames the byte stream on each side of the stdio pipe into newline-delimited JSON-RPC messages, correlates request ids with their responses, and records latency and error status. Source: src/store.ts:1-120
3. Session storage — appends correlated calls to JSONL files under ~/.mcptail/sessions/, one file per server run, via a SessionWriter that has a configurable size cap. Source: src/store.ts:120-220
4. Local UI + HTTP API — serves a small dashboard on a local port that lists sessions, shows a call timeline, and exposes endpoints for export (e.g. GET /api/export?file=...&format=har). Source: src/server.ts:1-160

The proxy follows a degrade-to-pipe philosophy: if recording fails, errors are written to stderr and the proxy still forwards traffic, so a broken tap never breaks the user's MCP client. Source: src/store.ts:200-260

Install

mcptail is a Node.js project. The recommended path is via npm:

npm install -g mcptail
mcptail --help

A local-from-source install is supported for contributors:

git clone https://github.com/Neal006/mcptail
cd mcptail
npm install
npm run build
node dist/cli.js --help

Source: package.json:1-60

The package declares CLI entry points, a build script that bundles the TypeScript sources in src/, and a test script that runs the Vitest suites under tests/. Source: package.json:30-80

Quickstart: from zero to a captured session

The minimum loop to get value out of mcptail is three commands. The example below assumes a Claude Desktop install — the same flow works for Cursor and Windsurf via their respective adapters.

# 1. Wrap every MCP server in your host config with `mcptail tap`.
mcptail init

# 2. Use your MCP client normally — call a few tools.
#    (mcptail runs in the background; the client sees no change.)

# 3. Open the dashboard and inspect the timeline.
mcptail ui

mcptail init is the only command that mutates a host config. It detects the active adapter, reads the existing mcpServers block, and rewrites each command to invoke mcptail tap first; the server's argv is preserved. Source: src/adapters/index.ts:40-120 Source: src/cli.ts:1-140

mcptail doctor is the companion command for verifying the wiring: it parses the host config, confirms each server is wrapped, and prints any drift between the config and what mcptail last recorded. Source: src/cli.ts:140-220

To undo the rewrite, run mcptail remove, which restores the original commands from mcptail's own bookkeeping file. Source: src/cli.ts:220-280

Common follow-up commands

Sessions accumulate forever by default, so mcptail clear (proposed in issue #12) is the expected first habit after experimenting. The size cap on SessionWriter (issue #13, default ~50 MB) protects a single chatty server from filling the disk before you remember to clean up. Source: tests/store.test.ts:1-80

Where to go next

• For adapter coverage (Claude Desktop, Cursor, Windsurf) and how to add a new host, see the Adapters page.
• For the session file format and the correlate() helper that powers diffing, see Session Storage & Replay.
• For UI work (keyboard nav, search, light theme) the active issues are #10, #11, and #15; all touch ui/src/app.tsx and ui/src/style.css.
• For the planned HTTP/SSE proxy mode, OpenTelemetry exporter, and "export as regression test" feature, track issues #18, #19, and #20 on GitHub.

Source: ROADMAP.md:30-120 Source: CONTRIBUTING.md:1-60

Related Pages

Related topics: Introduction and Quickstart, Client Adapters and Configuration Management, Dashboard, Replay, and Common Operations

System Architecture and Data Pipeline

mcptail is a record-and-replay proxy for Model Context Protocol (MCP) servers. It sits transparently between an MCP client (Cursor, Windsurf, Claude Desktop, …) and a stdio MCP server, parses the newline-delimited JSON-RPC traffic, correlates request/response pairs, persists them as session files on disk, and surfaces them through a local HTTP UI plus exportable artifacts. This page describes the moving parts and how a single tool call travels end-to-end through the system.

Component Layout

mcptail is organized as a CLI front-end that dispatches to one of several subsystems:

• CLI entry (src/cli.ts) — registers init, remove, doctor, clear, export, test, and the implicit proxy mode that wraps a child server. Source: src/cli.ts.
• Proxy (src/proxy.ts, src/taps.ts) — the core: it spawns (or attaches to) the upstream MCP server, splices its stdio through a framing layer, and emits a stream of normalized events. taps.ts defines the transport-specific behavior (stdio in v0.1, Streamable HTTP/SSE planned). Source: src/proxy.ts.
• Frame parser (src/frames.ts) — converts raw bytes into newline-delimited JSON-RPC frames, the smallest unit of the pipeline. Source: src/frames.ts.
• Session store (src/store.ts) — SessionWriter writes one JSONL file per session under ~/.mcptail/sessions/, with a planned size cap (issue #13) and pruning helpers (issue #12). Source: src/store.ts.
• Cost engine (src/cost.ts, src/pricing.json) — translates payload sizes into model-specific dollar estimates. Currently Claude-only (issue #9 asks for GPT and Gemini). Source: src/cost.ts.
• HTTP server (src/server.ts) — read-only API serving session files for the React UI and offering download endpoints (e.g. GET /api/export?format=har, issue #14). Source: src/server.ts.
• **Adapters (src/adapters/*.ts)** — translate each host client's MCP config file format (cursor.ts, the planned windsurf.ts per issue #6, more via index.ts). Source: src/adapters/index.ts.
• Replay / export (src/replay.ts, src/export.ts) — re-drive a recorded call against a server for testing (issue #20) and convert sessions to alternate formats such as HAR (issue #14). Source: src/replay.ts.

End-to-End Data Pipeline

The pipeline is best read as five stages: capture → frame → correlate → persist → serve/export. The diagram below summarizes the runtime path for a single tool call invoked from an MCP-aware editor.

flowchart LR
    A[MCP client<br>Cursor / Windsurf] -->|stdio JSON-RPC| B[mcptail proxy<br>src/proxy.ts]
    B --> C[Frame parser<br>src/frames.ts]
    C --> D[Correlator<br>matches id to response]
    D --> E[SessionWriter<br>src/store.ts]
    E --> F[(~/.mcptail/sessions/*.jsonl)]
    F --> G[HTTP server<br>src/server.ts]
    G --> H[React UI<br>ui/src/app.tsx]
    F --> I[Exporters<br>src/export.ts]
    D --> J[Cost engine<br>src/cost.ts]
    I --> K[HAR / OTel / test spec]

Capture starts when mcptail init rewrites the client's config to point at the proxy instead of the upstream server directly; the original command is preserved so the proxy can spawn the real server on first use. The proxy then owns both ends of the child's stdio. Source: src/cli.ts and src/proxy.ts.

Frames arriving from either direction are normalized by src/frames.ts, which keeps the rest of the pipeline transport-agnostic. This is the same layer the planned Streamable HTTP/SSE tap (issue #18) will plug into, so the correlator and storage paths do not change when remote transports are added.

The correlator joins outbound requests with their inbound responses using the JSON-RPC id and timestamps them, producing Call records that the UI can sort and filter (issues #10, #15). Correlator output is also the input to the cost engine, which reads src/pricing.json and annotates each call with an estimated input cost. Source: src/frames.ts and src/cost.ts.

Persistence is append-only JSONL (SessionWriter in src/store.ts), one file per session, which makes rotation (issue #13), pruning (mcptail clear, issue #12), and batch export (issue #19) straightforward — OTel exporters and the planned mcptail export --otlp both read from the same on-disk format rather than from the live proxy. Source: src/store.ts.

Serving and exporting share the same source of truth: src/server.ts exposes the JSONL files over HTTP, while src/export.ts converts them into portable artifacts such as HAR (issue #14). The planned OpenTelemetry exporter (issue #19) and regression-test exporter (issue #20) are additional readers over the same files, reusing src/replay.ts for the test-generation path.

Design Conventions and Extensibility

A few rules show up across modules and are worth knowing when contributing:

• Degrade-to-pipe philosophy. If recording fails — disk full, file too large (issue #13), JSON parse error — the proxy logs a single stderr warning and continues forwarding bytes. SessionWriter and the frame parser both follow this rule. Source: src/store.ts.
• One adapter per host client. New editors plug in by adding src/adapters/<name>.ts that round-trips the host's MCP config JSON, then registering it in src/adapters/index.ts. The Windsurf adapter (issue #6) is a ~15-line copy of cursor.ts. Source: src/adapters/cursor.ts.
• Pure diff helpers over correlate() output. Cross-cutting features like session diffing (issue #21) consume the same normalized Call objects the UI uses, so they can be tested without a live proxy. Source: src/proxy.ts.
• Pricing as data. Model costs live in src/pricing.json, not in code, so adding GPT or Gemini (issue #9) is a JSON edit plus a link to the provider's pricing page. Source: src/pricing.json.

These conventions keep the boundary between the always-on capture path and the optional analysis/export path clean: the proxy stays a fast pipe, while richer features (UI filters, HAR, OTel, regression tests) are layered on top of stable on-disk artifacts.

Related Pages

Related topics: Introduction and Quickstart, System Architecture and Data Pipeline

Client Adapters and Configuration Management

Purpose and Scope

mcptail integrates with multiple Model Context Protocol (MCP) clients, each of which stores its MCP server list in a different file format at a different path. The adapters subsystem isolates those client-specific details behind a small, uniform interface so that the rest of the codebase (proxying, recording, UI, exports) stays host-agnostic.

The current release ships with three built-in adapters — claude-code, cursor, and vscode — and the community backlog tracks additional clients such as Windsurf. Every adapter is responsible for three operations: locating the client's config file on disk, rewriting its mcpServers entries so the client's stdio transport is rerouted through the local mcptail proxy, and round-tripping the original server definitions back into place on remove.

Source: src/adapters/index.ts:1-30 Source: src/adapters/types.ts:1-40

Adapter Contract

The shared Adapter interface in src/adapters/types.ts defines the surface every adapter must implement. Its members are deliberately small:

• id — a short stable identifier (e.g. "claude-code", "cursor", "vscode") used on the CLI and in log output.
• configPath() — returns the absolute path of the client's MCP config file, resolved against platform conventions such as ~/.claude/, ~/.cursor/, or the VS Code user directory.
• apply(servers, options) — rewrites a list of MCP server entries so each entry's command/args is wrapped in a mcptail invocation while preserving the original arguments and environment.
• remove(servers) — the inverse of apply; restores the original command list when mcptail is detached from a client.
• doctor() — runs lightweight diagnostics and returns per-server status suitable for the mcptail doctor command.

apply and remove are kept symmetric so the same fixture can be round-tripped in tests without state drift, and so any future "diff two configurations" feature (raised in community discussion) can reuse the pair directly.

Source: src/adapters/types.ts:1-60 Source: src/adapters/index.ts:1-30

Built-in Adapters and CLI Integration

Three adapters ship with v0.1. Each module is intentionally small — typically under 50 lines — because the heavy lifting (proxying, recording, correlation, exports) lives in src/proxy.ts and src/store.ts and not in the adapter layer.

The CLI does not import each adapter by name. Instead, src/adapters/index.ts exports a registry object keyed by adapter id; src/cli.ts resolves a --client flag against that registry to dispatch init, remove, and doctor. The init flow reads the current file via the chosen adapter's configPath(), runs apply() against every mcpServers entry the user confirms, and writes the result back atomically. remove performs the inverse. doctor reports the result of the apply/remove round-trip plus proxy reachability. The same fixtures used by tests/taps.test.ts exercise this path so the CLI behavior stays aligned with the adapter contract.

The Windsurf adapter is a planned addition that follows the same shape as cursor.ts and reads ~/.codeium/windsurf/mcp_config.json under mcpServers; this work is tracked in the community backlog (issue #6) along with the accompanying fixture test.

Source: src/adapters/claude-code.ts:1-50 Source: src/adapters/cursor.ts:1-50 Source: src/adapters/vscode.ts:1-50 Source: src/cli.ts:1-120 Source: tests/taps.test.ts:1-40

Adding a New Adapter

The community-documented recipe for adding a new client (issue #6, Windsurf) is:

1. Create src/adapters/<name>.ts exporting an Adapter that satisfies src/adapters/types.ts. The body can start as a copy of cursor.ts and adjust only id, configPath(), and any client-specific field names — the documented Windsurf copy is expected to be roughly 15 lines.
2. Register the adapter in src/adapters/index.ts so --client <name> resolves through the registry.
3. Add a fixture round-trip test in tests/taps.test.ts that runs apply then remove against a sample config and asserts the original payload is restored byte-for-byte.
4. Verify mcptail init, mcptail remove, and mcptail doctor all pass against the new fixture in CI.

Because the adapter layer is deliberately thin, no changes are required in the proxy, store, or UI packages to support a new client — only the four steps above. This keeps the addition cost predictable and lets the project absorb new MCP hosts without expanding the surface area of the core recorder.

Source: src/adapters/index.ts:1-30 Source: src/adapters/types.ts:1-60 Source: src/adapters/cursor.ts:1-50 Source: src/cli.ts:1-120 Source: tests/taps.test.ts:1-40

Related Pages

Related topics: Introduction and Quickstart, System Architecture and Data Pipeline

Dashboard, Replay, and Common Operations

mcptail ships with a small web dashboard for inspecting captured MCP traffic, a replay engine for re-driving recorded JSON-RPC calls against a server, and a CLI surface for day-to-day operations such as init, doctor, remove, test, and clear. Together these three pieces form the operator-facing side of the project — the proxy records, the dashboard visualises, and the CLI/replay layer lets users replay or clean up.

Dashboard

The dashboard is a React app served by the local mcptail server. ui/src/main.tsx mounts the root component, and ui/src/app.tsx renders the timeline table that lists captured calls with their method/tool, latency, and status dot. Each row links to a detail view of the request and response bodies. ui/src/api.ts wraps fetch calls against the JSON endpoints exposed by the HTTP server in src/server.ts, so the UI speaks the same protocol the CLI uses.

Browser (ui/src/app.tsx)
        │  HTTP
        ▼
src/server.ts ──► session files on disk
        ▲
        │  same JSON shape
mcptail CLI (src/cli.ts)

The dashboard's current palette is dark-only (ui/src/style.css), and feature parity gaps are tracked in upstream issues: keyboard navigation (j/k + Enter) in #15, a light theme toggle in #11, and live substring search plus an errors-only toggle in #10. A planned download button behind GET /api/export?file=…&format=har (issue #14) will surface a HAR export route handled by src/export.ts.

Replay

Replay lives in src/replay.ts and consumes the same JSONL session files the proxy writes. It is the backbone of the planned "export a captured call as a regression test" workflow in issue #20: a captured call can be frozen into a YAML spec (server command, request, expected response matcher) and later run via mcptail test spec.yaml in CI. Replay is also the foundation for the session-diffing idea in issue #21, which proposes a pure diff helper over two correlate() outputs, aligned by method + tool, surfacing response diffs and latency deltas across runs.

# planned spec shape (issue #20)
server:  { command: ["npx", "@modelcontextprotocol/server-filesystem"] }
request: { method: "tools/call", params: { name: "read_file", arguments: … } }
expect:  { matcher: { path: "result", equals: … } }

Because replay operates on already-correlated JSON-RPC pairs, it does not need to know anything about the underlying transport; this is the same decoupling that lets stdio-only v0.1 (issue #18 notes the gap for Streamable HTTP / SSE) defer remote-transport support without rewriting the recorder.

Common CLI operations

The command surface in src/cli.ts covers the lifecycle of an mcptail installation:

• init — registers the proxy against an editor adapter (Cursor, Claude Code, Windsurf per issue #6, etc.) so the IDE launches MCP servers through mcptail.
• remove — undoes init for the same adapter.
• doctor — sanity-checks that the adapter's tap still points at mcptail and that ~/.mcptail/sessions/ is writable.
• test <spec.yaml> — runs a replay spec (see Replay above).
• clear — prunes recorded sessions; per issue #12 this should support mcptail clear (delete all) and mcptail clear --older-than 7d, printing a summary like removed 12 sessions, 3.2 MB. The helper backing these flags is in src/store.ts.

src/store.ts also owns the SessionWriter used by the proxy. Issue #13 proposes a per-session size cap (default ~50 MB, env-overridable) so a chatty server cannot grow a session file unbounded; when the cap is hit, SessionWriter should stop recording with a single stderr warning and continue piping traffic — the same degrade-to-pipe philosophy the rest of the proxy follows.

Pricing context for replayed payloads

Replayed payloads are still useful as input-context cost signals regardless of which model the user drives, so src/pricing.json is the single source of truth for $/MTok numbers shown next to each captured call. v0.1 lists Claude entries; issue #9 asks for OpenAI and Gemini input prices to be added alphabetically, with links to each provider's pricing page in the same PR. Keeping the file provider-agnostic lets the dashboard and export paths stay model-independent.

Known gaps and community requests

A bounded list of operator-facing work that the community has already filed:

• Streamable HTTP / SSE capture (#18) — v0.1 taps stdio only; a reverse-proxy mode is the proposed extension.
• OpenTelemetry exporter (#19) — batch-export correlated calls as OTel spans via mcptail export --otlp <endpoint>.
• Session size cap (#13), session prune clear (#12), HAR export (#14), session diffing (#21), regression-test export (#20), README translations (#16, #17), UI keyboard nav (#15), UI light theme (#11), UI search/filter (#10), Windsurf adapter (#6), and broader pricing coverage (#9).

These together describe the next operator-visible layer of mcptail beyond recording: search, diff, export, prune, and replay-as-test.

Doramagic Pitfall Log

Found 30 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Neal006/mcptail/issues/20

2. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Neal006/mcptail/issues/13

3. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/Neal006/mcptail

4. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: Adapter: Cline
• User impact: Developers may misconfigure credentials, environment, or host setup: Adapter: Cline
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Adapter: Cline. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/8

5. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: Adapter: Windsurf
• User impact: Developers may misconfigure credentials, environment, or host setup: Adapter: Windsurf
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Adapter: Windsurf. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/6

6. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: Adapter: Zed
• User impact: Developers may misconfigure credentials, environment, or host setup: Adapter: Zed
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Adapter: Zed. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/7

7. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: Streamable HTTP / SSE transport capture
• User impact: Developers may misconfigure credentials, environment, or host setup: Streamable HTTP / SSE transport capture
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Streamable HTTP / SSE transport capture. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/18

8. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/Neal006/mcptail

9. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Neal006/mcptail/issues/11

10. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Neal006/mcptail/issues/10

11. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Developers should check this migration risk before relying on the project: Add GPT and Gemini input prices to pricing.json
• User impact: Developers may hit a documented source-backed failure mode: Add GPT and Gemini input prices to pricing.json
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Add GPT and Gemini input prices to pricing.json. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/9

12. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Developers should check this migration risk before relying on the project: Session diffing — compare two runs of the same server
• User impact: Developers may hit a documented source-backed failure mode: Session diffing — compare two runs of the same server
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Session diffing — compare two runs of the same server. Context: Observed during version upgrade or migration.
• Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/21

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using mcptail with real data or production workflows.

• mcptail clear — prune recorded sessions - github / github_issue
• Add GPT and Gemini input prices to pricing.json - github / github_issue
• Adapter: Windsurf - github / github_issue
• Streamable HTTP / SSE transport capture - github / github_issue
• OpenTelemetry exporter - github / github_issue
• Export a captured call as a regression test - github / github_issue
• Session diffing — compare two runs of the same server - github / github_issue
• README translation: हिन्दी (hi) - github / github_issue
• Community source 9 - github / github_issue
• UI: keyboard navigation (j/k + enter) in the timeline - github / github_issue
• Export a session as HAR - github / github_issue
• Session log rotation: cap per-session file size - github / github_issue