From 75bcf9dec6a3ddf2fecea9bc5aee5d1e0467854c Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 17 Apr 2026 07:45:25 +0000
Subject: [PATCH 1/4] chore(master): release 0.37.0

---
 .release-please-manifest.json |  2 +-
 CHANGELOG.md                  | 19 +++++++++++++++++++
 Cargo.lock                    |  2 +-
 Cargo.toml                    |  2 +-
 4 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/.release-please-manifest.json b/.release-please-manifest.json
index 93c546c8d..05b60243f 100644
--- a/.release-please-manifest.json
+++ b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "0.36.0"
+  ".": "0.37.0"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 08cae60ae..688458579 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,25 @@ All notable changes to rtk (Rust Token Killer) will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.37.0](https://github.com/rtk-ai/rtk/compare/v0.36.0...v0.37.0) (2026-04-17)
+
+
+### Features
+
+* **discover:** handle more npm/npx/pnpm/pnpx patterns ([9e96caa](https://github.com/rtk-ai/rtk/commit/9e96caa0a18a95c84da82ba57716a9d3ef86d0c8))
+* **refacto-core:** binary hook w/ native cmd exec + streaming ([e7b7f9a](https://github.com/rtk-ai/rtk/commit/e7b7f9ab665a0f7303d41d23ad156d24e5e8964e))
+
+
+### Bug Fixes
+
+* **docs:** use release please changelog no manual ([7591a14](https://github.com/rtk-ai/rtk/commit/7591a14e4ceb732ab7ca160ac01a852926abe77a))
+* isolate cursor hook tests from local settings (determinist) ([d8ddefe](https://github.com/rtk-ai/rtk/commit/d8ddefe78efe25c35bb2a2f9083f2eacb9dd7274))
+* P0+P1 fixes from pre-merge review of hook engine ([df8e035](https://github.com/rtk-ai/rtk/commit/df8e03558d4d6cc2f5cbac91c63ab1b3b51d3bcd))
+* P0+P1 fixes from pre-merge review of hook engine ([d34389c](https://github.com/rtk-ai/rtk/commit/d34389c3d0936c2b0790e14f450bb50a28a7edf7))
+* rename ship.md to ship/SKILL.md to match develop ([5916ecd](https://github.com/rtk-ai/rtk/commit/5916ecd86fb319c2519a0b4fb2891309833a3bb4))
+* **runner:** preserve fd separation on command failure ([e92d099](https://github.com/rtk-ai/rtk/commit/e92d0993c93f0b732316dfa932d265aeca7488d6))
+* **stream:** missing stderr fields ([a1d46f3](https://github.com/rtk-ai/rtk/commit/a1d46f39c291e3356b9c26a062bde05ba1de591a))
+
 ## [0.36.0](https://github.com/rtk-ai/rtk/compare/v0.35.0...v0.36.0) (2026-04-13)
 
 
diff --git a/Cargo.lock b/Cargo.lock
index 7ad9dc981..29a041450 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -892,7 +892,7 @@ dependencies = [
 
 [[package]]
 name = "rtk"
-version = "0.36.0"
+version = "0.37.0"
 dependencies = [
  "anyhow",
  "automod",
diff --git a/Cargo.toml b/Cargo.toml
index 81cc9c1df..778af25ee 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "rtk"
-version = "0.34.3"
+version = "0.37.0"
 edition = "2021"
 authors = ["Patrick Szymkowiak"]
 description = "Rust Token Killer - High-performance CLI proxy to minimize LLM token consumption"

From 4deb5ad0f2ced719bfc743888c9639e74ffd34e7 Mon Sep 17 00:00:00 2001
From: CI <test@ci.com>
Date: Fri, 17 Apr 2026 18:39:14 +0400
Subject: [PATCH 2/4] feat: add MCP server for Claude Desktop integration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Exposes RTK's filter pipeline as a bash tool via Model Context Protocol,
enabling the same 60-90% token savings in Claude Desktop that Claude Code
users get via hooks.

Key additions:
- src/mcp/ — sync stdio JSON-RPC 2.0 server (no tokio, <10ms startup)
  - protocol.rs: Request/Response/Error types + MCP result structs
  - transport.rs: BufReader<Stdin> line-delimited reader + stdout writer
  - handler.rs: initialize/tools-list/tools-call/ping/shutdown dispatch
  - install.rs: writes rtk entry into claude_desktop_config.json (cross-platform)
- rtk mcp-serve: start the server
- rtk mcp-install: register in Claude Desktop config
- src/core/tracking.rs: add source column (hook|mcp|direct) to SQLite
  with backward-compatible ALTER TABLE migration; adds record_with_source()
  and track_with_source() for MCP-tagged entries
- tests/mcp_integration.rs: E2E tests (#[ignore]) — spawn binary, full
  JSON-RPC handshake over pipes, filter verification
- docs/MCP.md: install, verify, troubleshoot guide
- 41 unit tests covering all protocol types, handler methods, shell_split,
  and install helpers

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md                | 147 +++++++++++++
 docs/MCP.md              | 135 ++++++++++++
 src/core/tracking.rs     |  76 ++++++-
 src/main.rs              |  26 +++
 src/mcp/handler.rs       | 438 +++++++++++++++++++++++++++++++++++++++
 src/mcp/install.rs       | 194 +++++++++++++++++
 src/mcp/mod.rs           |  71 +++++++
 src/mcp/protocol.rs      | 222 ++++++++++++++++++++
 src/mcp/transport.rs     |  65 ++++++
 tests/mcp_integration.rs | 292 ++++++++++++++++++++++++++
 10 files changed, 1662 insertions(+), 4 deletions(-)
 create mode 100644 docs/MCP.md
 create mode 100644 src/mcp/handler.rs
 create mode 100644 src/mcp/install.rs
 create mode 100644 src/mcp/mod.rs
 create mode 100644 src/mcp/protocol.rs
 create mode 100644 src/mcp/transport.rs
 create mode 100644 tests/mcp_integration.rs

diff --git a/CLAUDE.md b/CLAUDE.md
index 9e89fff38..c5c67d482 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -77,6 +77,19 @@ Module responsibilities are documented in each folder's `README.md` and each fil
 
 Supported ecosystems: git/gh/gt, cargo, go/golangci-lint, npm/pnpm/npx, ruff/pytest/pip/mypy, rspec/rubocop/rake, dotnet, playwright/vitest/jest, docker/kubectl/aws.
 
+### MCP Server (Claude Desktop)
+
+RTK can run as an MCP server for Claude Desktop, exposing a `bash` tool that routes commands through the same filter pipeline.
+
+```bash
+rtk mcp-install    # Register RTK in Claude Desktop's config
+rtk mcp-serve      # Start the MCP stdio server (used by Claude Desktop)
+```
+
+See [docs/MCP.md](docs/MCP.md) for full setup and troubleshooting.
+
+**Module**: `src/mcp/` — protocol.rs (JSON-RPC types), transport.rs (stdio), handler.rs (dispatch), install.rs (installer).
+
 ### Proxy Mode
 
 **Purpose**: Execute commands without filtering but track usage for metrics.
@@ -169,3 +182,137 @@ When user provides a numbered plan (QW1-QW4, Phase 1-5, sprint tasks, etc.):
 3. **Never skip or reorder**: If a step is blocked, report it and ask before proceeding
 4. **Track progress**: Use task list (TaskCreate/TaskUpdate) for plans with 3+ steps
 5. **Validate assumptions**: Before starting, verify all referenced file paths exist and working directory is correct
+
+<!-- rtk-instructions v2 -->
+# RTK (Rust Token Killer) - Token-Optimized Commands
+
+## Golden Rule
+
+**Always prefix commands with `rtk`**. If RTK has a dedicated filter, it uses it. If not, it passes through unchanged. This means RTK is always safe to use.
+
+**Important**: Even in command chains with `&&`, use `rtk`:
+```bash
+# ❌ Wrong
+git add . && git commit -m "msg" && git push
+
+# ✅ Correct
+rtk git add . && rtk git commit -m "msg" && rtk git push
+```
+
+## RTK Commands by Workflow
+
+### Build & Compile (80-90% savings)
+```bash
+rtk cargo build         # Cargo build output
+rtk cargo check         # Cargo check output
+rtk cargo clippy        # Clippy warnings grouped by file (80%)
+rtk tsc                 # TypeScript errors grouped by file/code (83%)
+rtk lint                # ESLint/Biome violations grouped (84%)
+rtk prettier --check    # Files needing format only (70%)
+rtk next build          # Next.js build with route metrics (87%)
+```
+
+### Test (90-99% savings)
+```bash
+rtk cargo test          # Cargo test failures only (90%)
+rtk vitest run          # Vitest failures only (99.5%)
+rtk playwright test     # Playwright failures only (94%)
+rtk test <cmd>          # Generic test wrapper - failures only
+```
+
+### Git (59-80% savings)
+```bash
+rtk git status          # Compact status
+rtk git log             # Compact log (works with all git flags)
+rtk git diff            # Compact diff (80%)
+rtk git show            # Compact show (80%)
+rtk git add             # Ultra-compact confirmations (59%)
+rtk git commit          # Ultra-compact confirmations (59%)
+rtk git push            # Ultra-compact confirmations
+rtk git pull            # Ultra-compact confirmations
+rtk git branch          # Compact branch list
+rtk git fetch           # Compact fetch
+rtk git stash           # Compact stash
+rtk git worktree        # Compact worktree
+```
+
+Note: Git passthrough works for ALL subcommands, even those not explicitly listed.
+
+### GitHub (26-87% savings)
+```bash
+rtk gh pr view <num>    # Compact PR view (87%)
+rtk gh pr checks        # Compact PR checks (79%)
+rtk gh run list         # Compact workflow runs (82%)
+rtk gh issue list       # Compact issue list (80%)
+rtk gh api              # Compact API responses (26%)
+```
+
+### JavaScript/TypeScript Tooling (70-90% savings)
+```bash
+rtk pnpm list           # Compact dependency tree (70%)
+rtk pnpm outdated       # Compact outdated packages (80%)
+rtk pnpm install        # Compact install output (90%)
+rtk npm run <script>    # Compact npm script output
+rtk npx <cmd>           # Compact npx command output
+rtk prisma              # Prisma without ASCII art (88%)
+```
+
+### Files & Search (60-75% savings)
+```bash
+rtk ls <path>           # Tree format, compact (65%)
+rtk read <file>         # Code reading with filtering (60%)
+rtk grep <pattern>      # Search grouped by file (75%)
+rtk find <pattern>      # Find grouped by directory (70%)
+```
+
+### Analysis & Debug (70-90% savings)
+```bash
+rtk err <cmd>           # Filter errors only from any command
+rtk log <file>          # Deduplicated logs with counts
+rtk json <file>         # JSON structure without values
+rtk deps                # Dependency overview
+rtk env                 # Environment variables compact
+rtk summary <cmd>       # Smart summary of command output
+rtk diff                # Ultra-compact diffs
+```
+
+### Infrastructure (85% savings)
+```bash
+rtk docker ps           # Compact container list
+rtk docker images       # Compact image list
+rtk docker logs <c>     # Deduplicated logs
+rtk kubectl get         # Compact resource list
+rtk kubectl logs        # Deduplicated pod logs
+```
+
+### Network (65-70% savings)
+```bash
+rtk curl <url>          # Compact HTTP responses (70%)
+rtk wget <url>          # Compact download output (65%)
+```
+
+### Meta Commands
+```bash
+rtk gain                # View token savings statistics
+rtk gain --history      # View command history with savings
+rtk discover            # Analyze Claude Code sessions for missed RTK usage
+rtk proxy <cmd>         # Run command without filtering (for debugging)
+rtk init                # Add RTK instructions to CLAUDE.md
+rtk init --global       # Add RTK to ~/.claude/CLAUDE.md
+```
+
+## Token Savings Overview
+
+| Category | Commands | Typical Savings |
+|----------|----------|-----------------|
+| Tests | vitest, playwright, cargo test | 90-99% |
+| Build | next, tsc, lint, prettier | 70-87% |
+| Git | status, log, diff, add, commit | 59-80% |
+| GitHub | gh pr, gh run, gh issue | 26-87% |
+| Package Managers | pnpm, npm, npx | 70-90% |
+| Files | ls, read, grep, find | 60-75% |
+| Infrastructure | docker, kubectl | 85% |
+| Network | curl, wget | 65-70% |
+
+Overall average: **60-90% token reduction** on common development operations.
+<!-- /rtk-instructions -->
\ No newline at end of file
diff --git a/docs/MCP.md b/docs/MCP.md
new file mode 100644
index 000000000..7c7dc6781
--- /dev/null
+++ b/docs/MCP.md
@@ -0,0 +1,135 @@
+# RTK as an MCP Server (Claude Desktop)
+
+RTK works with Claude Desktop via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). It exposes a single `bash` tool that routes commands through RTK's filter pipeline — the same 60-90% token savings you get in Claude Code, now available in Claude Desktop.
+
+## Quick start
+
+**1. Build RTK**
+
+```bash
+cargo install --path .
+```
+
+**2. Register with Claude Desktop**
+
+```bash
+rtk mcp-install
+```
+
+This writes the MCP server entry into Claude Desktop's config file and prints the path that was updated.
+
+**3. Restart Claude Desktop**
+
+The server is loaded at startup. After restarting, open the tool picker — you should see a `bash` tool provided by `rtk`.
+
+---
+
+## Manual installation
+
+If `rtk mcp-install` doesn't work for your setup, add the server entry manually.
+
+**Config file locations:**
+
+| Platform | Path |
+|----------|------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+
+**Entry to add:**
+
+```json
+{
+  "mcpServers": {
+    "rtk": {
+      "command": "/full/path/to/rtk",
+      "args": ["mcp-serve"]
+    }
+  }
+}
+```
+
+Replace `/full/path/to/rtk` with the output of `which rtk`.
+
+---
+
+## How it works
+
+```
+Claude Desktop → tools/call bash {command: "git log -10"}
+                      ↓
+              rtk mcp-serve (this process)
+                      ↓
+              spawns: rtk git log -10
+                      ↓
+              RTK git filter (compact output)
+                      ↓
+              returns filtered text to Claude Desktop
+```
+
+- The MCP server is a **synchronous stdio JSON-RPC 2.0** process (no tokio, <10ms startup).
+- Every command is routed through the same RTK filter pipeline used by Claude Code hooks.
+- Token savings are tracked in `rtk gain` under the `mcp` source.
+
+---
+
+## Verifying it works
+
+Start the server manually and send a test request:
+
+```bash
+echo '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' | rtk mcp-serve
+```
+
+Expected output (one JSON line):
+
+```json
+{"jsonrpc":"2.0","result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"rtk","version":"0.37.0"}},"id":1}
+```
+
+Run `tools/list` to confirm the `bash` tool is registered:
+
+```bash
+printf '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}\n{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}\n' | rtk mcp-serve
+```
+
+---
+
+## Token savings via `rtk gain`
+
+MCP-sourced commands are tracked separately:
+
+```bash
+rtk gain           # total savings (all sources)
+rtk gain --history # shows source column: hook | mcp | direct
+```
+
+---
+
+## Troubleshooting
+
+**Claude Desktop doesn't show the bash tool**
+- Confirm the config file is valid JSON: `cat <config_path> | python3 -m json.tool`
+- Confirm the `command` path is absolute and the binary is executable: `chmod +x $(which rtk)`
+- Restart Claude Desktop after editing the config
+
+**`rtk mcp-install` says "Claude Desktop not installed"**
+- The installer checks for the config directory, not the app itself
+- Create the directory manually: `mkdir -p ~/Library/Application\ Support/Claude` (macOS)
+- Then re-run `rtk mcp-install`
+
+**Commands run without RTK filtering**
+- This happens if `rtk mcp-serve` can't locate itself via `current_exe()`
+- Use an absolute path in the config: `"command": "/usr/local/bin/rtk"`
+
+---
+
+## Integration tests
+
+Integration tests spawn the real binary and exercise the full handshake:
+
+```bash
+cargo build                                            # build first
+cargo test --test mcp_integration -- --ignored         # run all E2E tests
+cargo test --test mcp_integration test_initialize -- --ignored  # single test
+```
diff --git a/src/core/tracking.rs b/src/core/tracking.rs
index 982c937c4..abdda2eb6 100644
--- a/src/core/tracking.rs
+++ b/src/core/tracking.rs
@@ -308,6 +308,12 @@ impl Tracker {
             [],
         );
 
+        // Migration: add source column (hook | mcp | direct) for origin tracking
+        let _ = conn.execute(
+            "ALTER TABLE commands ADD COLUMN source TEXT DEFAULT 'hook'",
+            [],
+        );
+
         conn.execute(
             "CREATE TABLE IF NOT EXISTS parse_failures (
                 id INTEGER PRIMARY KEY,
@@ -366,18 +372,19 @@ impl Tracker {
         let project_path = current_project_path_string(); // added: record cwd
 
         self.conn.execute(
-            "INSERT INTO commands (timestamp, original_cmd, rtk_cmd, project_path, input_tokens, output_tokens, saved_tokens, savings_pct, exec_time_ms)
-             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)", // added: project_path
+            "INSERT INTO commands (timestamp, original_cmd, rtk_cmd, project_path, input_tokens, output_tokens, saved_tokens, savings_pct, exec_time_ms, source)
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)",
             params![
                 Utc::now().to_rfc3339(),
                 original_cmd,
                 rtk_cmd,
-                project_path, // added
+                project_path,
                 input_tokens as i64,
                 output_tokens as i64,
                 saved as i64,
                 pct,
-                exec_time_ms as i64
+                exec_time_ms as i64,
+                "hook"
             ],
         )?;
 
@@ -385,6 +392,43 @@ impl Tracker {
         Ok(())
     }
 
+    /// Record a command execution tagged with a specific source (`hook`, `mcp`, `direct`).
+    pub fn record_with_source(
+        &self,
+        original_cmd: &str,
+        rtk_cmd: &str,
+        input_tokens: usize,
+        output_tokens: usize,
+        exec_time_ms: u64,
+        source: &str,
+    ) -> Result<()> {
+        let saved = input_tokens.saturating_sub(output_tokens);
+        let pct = if input_tokens > 0 {
+            (saved as f64 / input_tokens as f64) * 100.0
+        } else {
+            0.0
+        };
+        let project_path = current_project_path_string();
+        self.conn.execute(
+            "INSERT INTO commands (timestamp, original_cmd, rtk_cmd, project_path, input_tokens, output_tokens, saved_tokens, savings_pct, exec_time_ms, source)
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)",
+            params![
+                Utc::now().to_rfc3339(),
+                original_cmd,
+                rtk_cmd,
+                project_path,
+                input_tokens as i64,
+                output_tokens as i64,
+                saved as i64,
+                pct,
+                exec_time_ms as i64,
+                source
+            ],
+        )?;
+        self.cleanup_old()?;
+        Ok(())
+    }
+
     fn cleanup_old(&self) -> Result<()> {
         let cutoff = Utc::now() - chrono::Duration::days(DEFAULT_HISTORY_DAYS);
         self.conn.execute(
@@ -1325,6 +1369,30 @@ impl TimedExecution {
     /// // ... execute streaming command ...
     /// timer.track_passthrough("git tag", "rtk git tag");
     /// ```
+    /// Track a command with an explicit source label (`hook`, `mcp`, `direct`).
+    pub fn track_with_source(
+        &self,
+        original_cmd: &str,
+        rtk_cmd: &str,
+        input: &str,
+        output: &str,
+        source: &str,
+    ) {
+        let elapsed_ms = self.start.elapsed().as_millis() as u64;
+        let input_tokens = estimate_tokens(input);
+        let output_tokens = estimate_tokens(output);
+        if let Ok(tracker) = Tracker::new() {
+            let _ = tracker.record_with_source(
+                original_cmd,
+                rtk_cmd,
+                input_tokens,
+                output_tokens,
+                elapsed_ms,
+                source,
+            );
+        }
+    }
+
     pub fn track_passthrough(&self, original_cmd: &str, rtk_cmd: &str) {
         let elapsed_ms = self.start.elapsed().as_millis() as u64;
         // input_tokens=0, output_tokens=0 won't dilute savings statistics
diff --git a/src/main.rs b/src/main.rs
index e8a19c2be..5325b5e3e 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -4,6 +4,7 @@ mod core;
 mod discover;
 mod hooks;
 mod learn;
+mod mcp;
 mod parser;
 
 // Re-export command modules for routing
@@ -721,6 +722,19 @@ enum Commands {
         args: Vec<String>,
     },
 
+    /// Start MCP (Model Context Protocol) server for Claude Desktop integration.
+    ///
+    /// Reads JSON-RPC 2.0 requests from stdin and writes responses to stdout.
+    /// Exposes a `bash` tool that routes commands through RTK's filter pipeline.
+    ///
+    /// Add to Claude Desktop via: rtk mcp-install
+    #[command(name = "mcp-serve")]
+    McpServe,
+
+    /// Install RTK as an MCP server in Claude Desktop's configuration.
+    #[command(name = "mcp-install")]
+    McpInstall,
+
     /// Hook processors for LLM CLI tools (Gemini CLI, Copilot, etc.)
     Hook {
         #[command(subcommand)]
@@ -1092,6 +1106,8 @@ const RTK_META_COMMANDS: &[&str] = &[
     "untrust",
     "session",
     "rewrite",
+    "mcp-serve",
+    "mcp-install",
 ];
 
 fn run_fallback(parse_error: clap::Error) -> Result<i32> {
@@ -2058,6 +2074,16 @@ fn run_cli() -> Result<i32> {
             0
         }
 
+        Commands::McpServe => {
+            mcp::serve()?;
+            0
+        }
+
+        Commands::McpInstall => {
+            mcp::install::run()?;
+            0
+        }
+
         Commands::Hook { command } => match command {
             HookCommands::Claude => {
                 hooks::hook_cmd::run_claude()?;
diff --git a/src/mcp/handler.rs b/src/mcp/handler.rs
new file mode 100644
index 000000000..8df47056e
--- /dev/null
+++ b/src/mcp/handler.rs
@@ -0,0 +1,438 @@
+use serde_json::{json, Value};
+
+use super::protocol::{
+    ContentItem, InitializeResult, ServerCapabilities, ServerInfo, Tool, ToolCallResult,
+    ToolsCapability, ToolsListResult, INVALID_PARAMS, METHOD_NOT_FOUND,
+};
+use super::protocol::{Response, PARSE_ERROR};
+
+pub fn handle(method: &str, params: &Value, id: Value) -> Response {
+    match method {
+        "initialize" => handle_initialize(id),
+        "tools/list" => handle_tools_list(id),
+        "tools/call" => handle_tools_call(params, id),
+        "ping" => Response::ok(id, json!({})),
+        "shutdown" => Response::ok(id, json!(null)),
+        _ => Response::err(
+            id,
+            METHOD_NOT_FOUND,
+            format!("Method not found: {}", method),
+        ),
+    }
+}
+
+fn handle_initialize(id: Value) -> Response {
+    let result = InitializeResult {
+        protocol_version: "2024-11-05",
+        capabilities: ServerCapabilities {
+            tools: ToolsCapability {},
+        },
+        server_info: ServerInfo {
+            name: "rtk",
+            version: env!("CARGO_PKG_VERSION"),
+        },
+    };
+    match serde_json::to_value(result) {
+        Ok(v) => Response::ok(id, v),
+        Err(e) => Response::err(id, PARSE_ERROR, format!("Serialization error: {}", e)),
+    }
+}
+
+fn handle_tools_list(id: Value) -> Response {
+    let tools = vec![Tool {
+        name: "bash",
+        description: "Execute a shell command with RTK token-optimized output filtering \
+                       (60-90% token savings on git, cargo, npm, pnpm, vitest, playwright, \
+                       docker, kubectl, and more).",
+        input_schema: json!({
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "string",
+                    "description": "The shell command to execute"
+                },
+                "description": {
+                    "type": "string",
+                    "description": "Human-readable description of the command (optional)"
+                },
+                "timeout": {
+                    "type": "number",
+                    "description": "Timeout in milliseconds (optional, default: no timeout)"
+                }
+            },
+            "required": ["command"]
+        }),
+    }];
+    let result = ToolsListResult { tools };
+    match serde_json::to_value(result) {
+        Ok(v) => Response::ok(id, v),
+        Err(e) => Response::err(id, PARSE_ERROR, format!("Serialization error: {}", e)),
+    }
+}
+
+fn handle_tools_call(params: &Value, id: Value) -> Response {
+    let name = match params.get("name").and_then(|v| v.as_str()) {
+        Some(n) => n,
+        None => return Response::err(id, INVALID_PARAMS, "Missing 'name' in tool call"),
+    };
+
+    if name != "bash" {
+        return Response::err(id, INVALID_PARAMS, format!("Unknown tool: {}", name));
+    }
+
+    let command = match params
+        .get("arguments")
+        .and_then(|a| a.get("command"))
+        .and_then(|c| c.as_str())
+    {
+        Some(c) => c.to_string(),
+        None => return Response::err(id, INVALID_PARAMS, "Missing 'command' in bash arguments"),
+    };
+
+    let timer = crate::core::tracking::TimedExecution::start();
+    let (output, exit_code) = run_with_rtk(&command);
+    timer.track_with_source(
+        &command,
+        &format!("rtk mcp: {}", command),
+        "",
+        &output,
+        "mcp",
+    );
+
+    let result = ToolCallResult {
+        content: vec![ContentItem {
+            content_type: "text",
+            text: output,
+        }],
+        is_error: exit_code != 0,
+    };
+    match serde_json::to_value(result) {
+        Ok(v) => Response::ok(id, v),
+        Err(e) => Response::err(id, PARSE_ERROR, format!("Serialization error: {}", e)),
+    }
+}
+
+/// Run a command string through the current RTK binary for filter-aware execution.
+/// Falls back to raw `sh -c` if RTK re-invocation fails.
+///
+/// In test builds we skip the RTK re-invocation because `current_exe()` returns
+/// the cargo test harness binary. Integration tests cover the RTK filter path.
+fn run_with_rtk(command: &str) -> (String, i32) {
+    #[cfg(test)]
+    return run_raw_shell(command);
+
+    #[cfg(not(test))]
+    run_with_rtk_binary(command)
+}
+
+#[cfg(not(test))]
+fn run_with_rtk_binary(command: &str) -> (String, i32) {
+    let args = shell_split(command);
+    if args.is_empty() {
+        return (String::new(), 0);
+    }
+
+    // Use current RTK binary so filters are always applied
+    let rtk_exe = std::env::current_exe().unwrap_or_else(|_| std::path::PathBuf::from("rtk"));
+
+    match std::process::Command::new(&rtk_exe)
+        .args(&args)
+        .stdout(std::process::Stdio::piped())
+        .stderr(std::process::Stdio::piped())
+        .output()
+    {
+        Ok(output) => {
+            let exit_code = output.status.code().unwrap_or(1);
+            let stdout = String::from_utf8_lossy(&output.stdout).into_owned();
+            let stderr = String::from_utf8_lossy(&output.stderr).into_owned();
+            let combined = merge_output(stdout, stderr);
+            (combined, exit_code)
+        }
+        Err(e) => {
+            // RTK re-invocation failed — fall back to raw shell execution
+            eprintln!(
+                "rtk mcp: rtk re-invoke failed ({}), falling back to raw shell",
+                e
+            );
+            run_raw_shell(command)
+        }
+    }
+}
+
+/// Last-resort fallback: execute command via system shell, no filtering.
+fn run_raw_shell(command: &str) -> (String, i32) {
+    let shell_result = {
+        #[cfg(target_os = "windows")]
+        {
+            std::process::Command::new("cmd")
+                .args(["/C", command])
+                .stdout(std::process::Stdio::piped())
+                .stderr(std::process::Stdio::piped())
+                .output()
+        }
+        #[cfg(not(target_os = "windows"))]
+        {
+            std::process::Command::new("sh")
+                .args(["-c", command])
+                .stdout(std::process::Stdio::piped())
+                .stderr(std::process::Stdio::piped())
+                .output()
+        }
+    };
+
+    match shell_result {
+        Ok(output) => {
+            let exit_code = output.status.code().unwrap_or(1);
+            let stdout = String::from_utf8_lossy(&output.stdout).into_owned();
+            let stderr = String::from_utf8_lossy(&output.stderr).into_owned();
+            (merge_output(stdout, stderr), exit_code)
+        }
+        Err(e) => (format!("rtk mcp: failed to execute command: {}", e), 1),
+    }
+}
+
+fn merge_output(mut stdout: String, stderr: String) -> String {
+    if !stderr.is_empty() {
+        if !stdout.is_empty() && !stdout.ends_with('\n') {
+            stdout.push('\n');
+        }
+        stdout.push_str(&stderr);
+    }
+    stdout
+}
+
+/// Minimal POSIX shell-word splitter.
+/// Handles double quotes, single quotes, and backslash escapes.
+pub fn shell_split(s: &str) -> Vec<String> {
+    let mut args: Vec<String> = Vec::new();
+    let mut current = String::new();
+    let mut chars = s.chars().peekable();
+
+    while let Some(c) = chars.next() {
+        match c {
+            ' ' | '\t' | '\n' => {
+                if !current.is_empty() {
+                    args.push(std::mem::take(&mut current));
+                }
+            }
+            '"' => {
+                while let Some(c2) = chars.next() {
+                    match c2 {
+                        '"' => break,
+                        '\\' => {
+                            if let Some(c3) = chars.next() {
+                                current.push(c3);
+                            }
+                        }
+                        _ => current.push(c2),
+                    }
+                }
+            }
+            '\'' => {
+                for c2 in chars.by_ref() {
+                    if c2 == '\'' {
+                        break;
+                    }
+                    current.push(c2);
+                }
+            }
+            '\\' => {
+                if let Some(c2) = chars.next() {
+                    current.push(c2);
+                }
+            }
+            _ => current.push(c),
+        }
+    }
+    if !current.is_empty() {
+        args.push(current);
+    }
+    args
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    // ── shell_split tests ────────────────────────────────────────────────────
+
+    #[test]
+    fn test_shell_split_simple() {
+        assert_eq!(shell_split("git status"), vec!["git", "status"]);
+    }
+
+    #[test]
+    fn test_shell_split_double_quotes() {
+        assert_eq!(
+            shell_split(r#"git commit -m "fix bug""#),
+            vec!["git", "commit", "-m", "fix bug"]
+        );
+    }
+
+    #[test]
+    fn test_shell_split_single_quotes() {
+        assert_eq!(
+            shell_split("echo 'hello world'"),
+            vec!["echo", "hello world"]
+        );
+    }
+
+    #[test]
+    fn test_shell_split_backslash_escape() {
+        assert_eq!(
+            shell_split(r"echo hello\ world"),
+            vec!["echo", "hello world"]
+        );
+    }
+
+    #[test]
+    fn test_shell_split_empty() {
+        assert!(shell_split("").is_empty());
+    }
+
+    #[test]
+    fn test_shell_split_whitespace_only() {
+        assert!(shell_split("   ").is_empty());
+    }
+
+    #[test]
+    fn test_shell_split_multiple_spaces() {
+        assert_eq!(shell_split("a  b   c"), vec!["a", "b", "c"]);
+    }
+
+    // ── handler tests ────────────────────────────────────────────────────────
+
+    #[test]
+    fn test_handle_ping() {
+        let r = handle("ping", &json!({}), json!(5));
+        let s = serde_json::to_string(&r).unwrap();
+        assert!(s.contains("\"result\""));
+        assert!(!s.contains("\"error\""));
+    }
+
+    #[test]
+    fn test_handle_unknown_method() {
+        let r = handle("unknown/method", &json!({}), json!(9));
+        let s = serde_json::to_string(&r).unwrap();
+        assert!(s.contains("\"error\""));
+        assert!(s.contains("-32601"));
+    }
+
+    #[test]
+    fn test_handle_initialize_returns_protocol_version() {
+        let r = handle("initialize", &json!({}), json!(1));
+        let v: serde_json::Value =
+            serde_json::from_str(&serde_json::to_string(&r).unwrap()).unwrap();
+        let version = v["result"]["protocolVersion"].as_str().unwrap_or("");
+        assert_eq!(version, "2024-11-05");
+    }
+
+    #[test]
+    fn test_handle_initialize_returns_server_info() {
+        let r = handle("initialize", &json!({}), json!(1));
+        let v: serde_json::Value =
+            serde_json::from_str(&serde_json::to_string(&r).unwrap()).unwrap();
+        assert_eq!(v["result"]["serverInfo"]["name"].as_str().unwrap(), "rtk");
+    }
+
+    #[test]
+    fn test_handle_tools_list_returns_bash() {
+        let r = handle("tools/list", &json!({}), json!(2));
+        let v: serde_json::Value =
+            serde_json::from_str(&serde_json::to_string(&r).unwrap()).unwrap();
+        let tools = v["result"]["tools"].as_array().unwrap();
+        assert!(!tools.is_empty());
+        assert_eq!(tools[0]["name"].as_str().unwrap(), "bash");
+    }
+
+    #[test]
+    fn test_handle_tools_list_bash_has_input_schema() {
+        let r = handle("tools/list", &json!({}), json!(2));
+        let v: serde_json::Value =
+            serde_json::from_str(&serde_json::to_string(&r).unwrap()).unwrap();
+        let schema = &v["result"]["tools"][0]["inputSchema"];
+        assert_eq!(schema["type"].as_str().unwrap(), "object");
+        assert!(schema["properties"]["command"].is_object());
+    }
+
+    #[test]
+    fn test_handle_tools_call_missing_name() {
+        let params = json!({"arguments": {"command": "ls"}});
+        let r = handle("tools/call", &params, json!(3));
+        let s = serde_json::to_string(&r).unwrap();
+        assert!(s.contains("\"error\""));
+        assert!(s.contains("-32602"));
+    }
+
+    #[test]
+    fn test_handle_tools_call_unknown_tool() {
+        let params = json!({"name": "unknown_tool", "arguments": {}});
+        let r = handle("tools/call", &params, json!(3));
+        let s = serde_json::to_string(&r).unwrap();
+        assert!(s.contains("\"error\""));
+        assert!(s.contains("-32602"));
+    }
+
+    #[test]
+    fn test_handle_tools_call_missing_command() {
+        let params = json!({"name": "bash", "arguments": {}});
+        let r = handle("tools/call", &params, json!(3));
+        let s = serde_json::to_string(&r).unwrap();
+        assert!(s.contains("\"error\""));
+        assert!(s.contains("-32602"));
+    }
+
+    #[test]
+    fn test_handle_tools_call_bash_executes() {
+        let params = json!({
+            "name": "bash",
+            "arguments": {"command": "echo hello_rtk_mcp"}
+        });
+        let r = handle("tools/call", &params, json!(4));
+        let v: serde_json::Value =
+            serde_json::from_str(&serde_json::to_string(&r).unwrap()).unwrap();
+        // Should be a result (no error key at top level)
+        assert!(v.get("result").is_some(), "expected result, got: {}", v);
+        let text = v["result"]["content"][0]["text"].as_str().unwrap_or("");
+        assert!(
+            text.contains("hello_rtk_mcp"),
+            "expected echo output, got: {:?}",
+            text
+        );
+    }
+
+    #[test]
+    fn test_handle_tools_call_failing_command_sets_is_error() {
+        // Use `sh -c "exit 1"` style via the raw shell fallback (cfg(test) path)
+        let params = json!({
+            "name": "bash",
+            "arguments": {"command": "sh -c 'exit 1'"}
+        });
+        let r = handle("tools/call", &params, json!(5));
+        let v: serde_json::Value =
+            serde_json::from_str(&serde_json::to_string(&r).unwrap()).unwrap();
+        assert!(v.get("result").is_some());
+        assert_eq!(v["result"]["isError"].as_bool(), Some(true));
+    }
+
+    #[test]
+    fn test_handle_shutdown() {
+        let r = handle("shutdown", &json!({}), json!(99));
+        let s = serde_json::to_string(&r).unwrap();
+        assert!(s.contains("\"result\""));
+    }
+
+    #[test]
+    fn test_merge_output_appends_stderr() {
+        let out = merge_output("stdout line".to_string(), "stderr line".to_string());
+        assert!(out.contains("stdout line"));
+        assert!(out.contains("stderr line"));
+    }
+
+    #[test]
+    fn test_merge_output_empty_stderr() {
+        let out = merge_output("only stdout".to_string(), String::new());
+        assert_eq!(out, "only stdout");
+    }
+}
diff --git a/src/mcp/install.rs b/src/mcp/install.rs
new file mode 100644
index 000000000..f0e28deb3
--- /dev/null
+++ b/src/mcp/install.rs
@@ -0,0 +1,194 @@
+use anyhow::{Context, Result};
+use serde_json::Value;
+use std::path::PathBuf;
+
+/// Install RTK as an MCP server in Claude Desktop's configuration.
+pub fn run() -> Result<()> {
+    let rtk_exe = std::env::current_exe().context("Could not determine RTK binary path")?;
+    let rtk_path = rtk_exe.to_string_lossy().into_owned();
+
+    let config_path = claude_desktop_config_path()
+        .context("Could not determine Claude Desktop config path — is Claude Desktop installed?")?;
+
+    if !config_path.exists() {
+        // Create the file with a fresh config
+        if let Some(parent) = config_path.parent() {
+            std::fs::create_dir_all(parent).with_context(|| {
+                format!("Could not create config directory: {}", parent.display())
+            })?;
+        }
+        let fresh = build_config_with_rtk(&rtk_path);
+        let json = serde_json::to_string_pretty(&fresh).context("Failed to serialize config")?;
+        std::fs::write(&config_path, json)
+            .with_context(|| format!("Failed to write {}", config_path.display()))?;
+        println!("Created: {}", config_path.display());
+        println!("RTK MCP server registered. Restart Claude Desktop to activate.");
+        return Ok(());
+    }
+
+    // Patch existing config
+    let existing = std::fs::read_to_string(&config_path)
+        .with_context(|| format!("Failed to read {}", config_path.display()))?;
+    let mut config: Value = serde_json::from_str(&existing)
+        .with_context(|| format!("Failed to parse {}: not valid JSON", config_path.display()))?;
+
+    if is_already_installed(&config) {
+        println!(
+            "RTK MCP server is already registered in {}",
+            config_path.display()
+        );
+        println!("Run `rtk mcp-serve` to verify it works.");
+        return Ok(());
+    }
+
+    inject_rtk_server(&mut config, &rtk_path);
+
+    let patched =
+        serde_json::to_string_pretty(&config).context("Failed to serialize patched config")?;
+    std::fs::write(&config_path, patched)
+        .with_context(|| format!("Failed to write {}", config_path.display()))?;
+
+    println!("Updated: {}", config_path.display());
+    println!("RTK MCP server registered. Restart Claude Desktop to activate.");
+    Ok(())
+}
+
+fn is_already_installed(config: &Value) -> bool {
+    config
+        .get("mcpServers")
+        .and_then(|s| s.get("rtk"))
+        .is_some()
+}
+
+fn inject_rtk_server(config: &mut Value, rtk_path: &str) {
+    let servers = config
+        .as_object_mut()
+        .map(|obj| {
+            obj.entry("mcpServers")
+                .or_insert_with(|| Value::Object(serde_json::Map::new()))
+        })
+        .and_then(|v| v.as_object_mut());
+
+    if let Some(servers_map) = servers {
+        servers_map.insert(
+            "rtk".to_string(),
+            serde_json::json!({
+                "command": rtk_path,
+                "args": ["mcp-serve"]
+            }),
+        );
+    }
+}
+
+fn build_config_with_rtk(rtk_path: &str) -> Value {
+    serde_json::json!({
+        "mcpServers": {
+            "rtk": {
+                "command": rtk_path,
+                "args": ["mcp-serve"]
+            }
+        }
+    })
+}
+
+fn claude_desktop_config_path() -> Option<PathBuf> {
+    let base = dirs::config_dir()?;
+
+    #[cfg(target_os = "macos")]
+    {
+        // macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
+        // dirs::config_dir() on macOS returns ~/Library/Application Support
+        Some(base.join("Claude").join("claude_desktop_config.json"))
+    }
+
+    #[cfg(target_os = "windows")]
+    {
+        // Windows: %APPDATA%\Claude\claude_desktop_config.json
+        // dirs::config_dir() on Windows returns %APPDATA%\Roaming
+        Some(base.join("Claude").join("claude_desktop_config.json"))
+    }
+
+    #[cfg(not(any(target_os = "macos", target_os = "windows")))]
+    {
+        // Linux: ~/.config/Claude/claude_desktop_config.json
+        Some(base.join("Claude").join("claude_desktop_config.json"))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn test_is_already_installed_true() {
+        let config = json!({
+            "mcpServers": {
+                "rtk": {"command": "/usr/bin/rtk", "args": ["mcp-serve"]}
+            }
+        });
+        assert!(is_already_installed(&config));
+    }
+
+    #[test]
+    fn test_is_already_installed_false_empty() {
+        let config = json!({});
+        assert!(!is_already_installed(&config));
+    }
+
+    #[test]
+    fn test_is_already_installed_false_other_servers() {
+        let config = json!({
+            "mcpServers": {
+                "other": {"command": "other-binary"}
+            }
+        });
+        assert!(!is_already_installed(&config));
+    }
+
+    #[test]
+    fn test_inject_rtk_server_creates_mcp_servers() {
+        let mut config = json!({});
+        inject_rtk_server(&mut config, "/usr/bin/rtk");
+        assert!(config["mcpServers"]["rtk"]["command"].as_str().is_some());
+        assert_eq!(
+            config["mcpServers"]["rtk"]["args"][0].as_str().unwrap(),
+            "mcp-serve"
+        );
+    }
+
+    #[test]
+    fn test_inject_rtk_server_preserves_existing_servers() {
+        let mut config = json!({
+            "mcpServers": {
+                "other": {"command": "other-binary"}
+            }
+        });
+        inject_rtk_server(&mut config, "/usr/bin/rtk");
+        assert!(config["mcpServers"]["other"].is_object());
+        assert!(config["mcpServers"]["rtk"].is_object());
+    }
+
+    #[test]
+    fn test_build_config_with_rtk() {
+        let config = build_config_with_rtk("/usr/local/bin/rtk");
+        assert_eq!(
+            config["mcpServers"]["rtk"]["command"].as_str().unwrap(),
+            "/usr/local/bin/rtk"
+        );
+        assert_eq!(
+            config["mcpServers"]["rtk"]["args"][0].as_str().unwrap(),
+            "mcp-serve"
+        );
+    }
+
+    #[test]
+    fn test_inject_idempotent_after_double_inject() {
+        let mut config = json!({});
+        inject_rtk_server(&mut config, "/usr/bin/rtk");
+        inject_rtk_server(&mut config, "/usr/bin/rtk");
+        // Still just one rtk entry
+        let servers = config["mcpServers"].as_object().unwrap();
+        assert_eq!(servers.len(), 1);
+    }
+}
diff --git a/src/mcp/mod.rs b/src/mcp/mod.rs
new file mode 100644
index 000000000..15b3b8870
--- /dev/null
+++ b/src/mcp/mod.rs
@@ -0,0 +1,71 @@
+//! MCP (Model Context Protocol) server for Claude Desktop integration.
+//!
+//! Implements a synchronous stdio JSON-RPC 2.0 server that exposes RTK's
+//! filter pipeline as a `bash` tool. Claude Desktop sends tool calls here;
+//! RTK routes each command through its existing filters before returning
+//! token-optimized output.
+//!
+//! Start the server: `rtk mcp-serve`
+//! Install into Claude Desktop: `rtk mcp-install`
+
+mod handler;
+pub mod install;
+pub mod protocol;
+pub mod transport;
+
+use anyhow::Result;
+use serde_json::Value;
+
+/// Run the MCP stdio server (blocking, single-threaded).
+///
+/// Reads newline-delimited JSON-RPC requests from stdin, dispatches to
+/// the appropriate handler, and writes responses to stdout.
+/// Exits cleanly on EOF or a `shutdown` request.
+pub fn serve() -> Result<()> {
+    let mut transport = transport::Transport::new();
+
+    loop {
+        let line = match transport.read_line()? {
+            Some(l) => l,
+            None => break, // EOF — client disconnected
+        };
+
+        if line.trim().is_empty() {
+            continue;
+        }
+
+        match serde_json::from_str::<protocol::Request>(&line) {
+            Ok(req) => {
+                // Notifications have no `id` — do not send a response.
+                if req.id.is_none() {
+                    continue;
+                }
+
+                let id = req.id.clone().unwrap_or(Value::Null);
+                let is_shutdown = req.method == "shutdown";
+
+                let response = handler::handle(&req.method, &req.params, id);
+                let json = serde_json::to_string(&response)
+                    .unwrap_or_else(|e| format!("{{\"jsonrpc\":\"2.0\",\"error\":{{\"code\":-32603,\"message\":\"{}\"}},\"id\":null}}", e));
+                transport.write_response(&json)?;
+
+                if is_shutdown {
+                    break;
+                }
+            }
+            Err(e) => {
+                let error_response = protocol::Response::err(
+                    Value::Null,
+                    protocol::PARSE_ERROR,
+                    format!("Parse error: {}", e),
+                );
+                let json = serde_json::to_string(&error_response).unwrap_or_else(|_| {
+                    "{\"jsonrpc\":\"2.0\",\"error\":{\"code\":-32700,\"message\":\"parse error\"},\"id\":null}".to_string()
+                });
+                transport.write_response(&json)?;
+            }
+        }
+    }
+
+    Ok(())
+}
diff --git a/src/mcp/protocol.rs b/src/mcp/protocol.rs
new file mode 100644
index 000000000..a8688dcde
--- /dev/null
+++ b/src/mcp/protocol.rs
@@ -0,0 +1,222 @@
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+/// Incoming JSON-RPC 2.0 message (request or notification).
+#[derive(Debug, Deserialize)]
+pub struct Request {
+    #[allow(dead_code)] // validated implicitly by serde; not read in handler
+    pub jsonrpc: String,
+    pub method: String,
+    #[serde(default)]
+    pub params: Value,
+    /// Absent for notifications; present for requests.
+    pub id: Option<Value>,
+}
+
+/// Outgoing JSON-RPC 2.0 response.
+#[derive(Debug, Serialize)]
+pub struct Response {
+    pub jsonrpc: &'static str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub result: Option<Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub error: Option<RpcError>,
+    pub id: Value,
+}
+
+impl Response {
+    pub fn ok(id: Value, result: Value) -> Self {
+        Self {
+            jsonrpc: "2.0",
+            result: Some(result),
+            error: None,
+            id,
+        }
+    }
+
+    pub fn err(id: Value, code: i32, message: impl Into<String>) -> Self {
+        Self {
+            jsonrpc: "2.0",
+            result: None,
+            error: Some(RpcError {
+                code,
+                message: message.into(),
+            }),
+            id,
+        }
+    }
+}
+
+#[derive(Debug, Serialize)]
+pub struct RpcError {
+    pub code: i32,
+    pub message: String,
+}
+
+// ── MCP result types ──────────────────────────────────────────────────────────
+
+#[derive(Debug, Serialize)]
+pub struct InitializeResult {
+    #[serde(rename = "protocolVersion")]
+    pub protocol_version: &'static str,
+    pub capabilities: ServerCapabilities,
+    #[serde(rename = "serverInfo")]
+    pub server_info: ServerInfo,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ServerInfo {
+    pub name: &'static str,
+    pub version: &'static str,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ServerCapabilities {
+    pub tools: ToolsCapability,
+}
+
+/// Signals to the client that `tools/list` and `tools/call` are supported.
+#[derive(Debug, Serialize)]
+pub struct ToolsCapability {}
+
+#[derive(Debug, Serialize)]
+pub struct Tool {
+    pub name: &'static str,
+    pub description: &'static str,
+    #[serde(rename = "inputSchema")]
+    pub input_schema: Value,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ToolsListResult {
+    pub tools: Vec<Tool>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ContentItem {
+    #[serde(rename = "type")]
+    pub content_type: &'static str,
+    pub text: String,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ToolCallResult {
+    pub content: Vec<ContentItem>,
+    #[serde(rename = "isError")]
+    pub is_error: bool,
+}
+
+// ── JSON-RPC error codes ──────────────────────────────────────────────────────
+
+pub const PARSE_ERROR: i32 = -32700;
+pub const METHOD_NOT_FOUND: i32 = -32601;
+pub const INVALID_PARAMS: i32 = -32602;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn test_request_deserialize_with_id() {
+        let raw = r#"{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}"#;
+        let req: Request = serde_json::from_str(raw).expect("parse failed");
+        assert_eq!(req.method, "tools/list");
+        assert_eq!(req.id, Some(json!(1)));
+    }
+
+    #[test]
+    fn test_request_deserialize_notification() {
+        let raw = r#"{"jsonrpc":"2.0","method":"initialized","params":{}}"#;
+        let req: Request = serde_json::from_str(raw).expect("parse failed");
+        assert_eq!(req.method, "initialized");
+        assert!(req.id.is_none());
+    }
+
+    #[test]
+    fn test_request_no_params_defaults_to_null() {
+        let raw = r#"{"jsonrpc":"2.0","method":"ping","id":2}"#;
+        let req: Request = serde_json::from_str(raw).expect("parse failed");
+        assert!(req.params.is_null());
+    }
+
+    #[test]
+    fn test_response_ok_serializes() {
+        let r = Response::ok(json!(1), json!({"answer": 42}));
+        let s = serde_json::to_string(&r).unwrap();
+        assert!(s.contains("\"result\""));
+        assert!(!s.contains("\"error\""));
+        assert!(s.contains("\"id\":1"));
+    }
+
+    #[test]
+    fn test_response_err_serializes() {
+        let r = Response::err(json!(3), METHOD_NOT_FOUND, "Method not found");
+        let s = serde_json::to_string(&r).unwrap();
+        assert!(s.contains("\"error\""));
+        assert!(!s.contains("\"result\""));
+        assert!(s.contains("-32601"));
+    }
+
+    #[test]
+    fn test_response_err_omits_result_field() {
+        let r = Response::err(json!(null), PARSE_ERROR, "bad json");
+        let serialized = serde_json::to_string(&r).unwrap();
+        let v: serde_json::Value = serde_json::from_str(&serialized).unwrap();
+        assert!(v.get("result").is_none(), "result should be omitted");
+        assert!(v.get("error").is_some());
+    }
+
+    #[test]
+    fn test_response_ok_omits_error_field() {
+        let r = Response::ok(json!(1), json!({}));
+        let serialized = serde_json::to_string(&r).unwrap();
+        let v: serde_json::Value = serde_json::from_str(&serialized).unwrap();
+        assert!(v.get("error").is_none(), "error should be omitted");
+        assert!(v.get("result").is_some());
+    }
+
+    #[test]
+    fn test_initialize_result_serializes() {
+        let r = InitializeResult {
+            protocol_version: "2024-11-05",
+            capabilities: ServerCapabilities {
+                tools: ToolsCapability {},
+            },
+            server_info: ServerInfo {
+                name: "rtk",
+                version: "0.37.0",
+            },
+        };
+        let s = serde_json::to_string(&r).unwrap();
+        assert!(s.contains("protocolVersion"));
+        assert!(s.contains("2024-11-05"));
+        assert!(s.contains("serverInfo"));
+    }
+
+    #[test]
+    fn test_tool_call_result_is_error_true() {
+        let r = ToolCallResult {
+            content: vec![ContentItem {
+                content_type: "text",
+                text: "error output".to_string(),
+            }],
+            is_error: true,
+        };
+        let s = serde_json::to_string(&r).unwrap();
+        assert!(s.contains("\"isError\":true"));
+    }
+
+    #[test]
+    fn test_tool_call_result_is_error_false() {
+        let r = ToolCallResult {
+            content: vec![ContentItem {
+                content_type: "text",
+                text: "ok output".to_string(),
+            }],
+            is_error: false,
+        };
+        let s = serde_json::to_string(&r).unwrap();
+        assert!(s.contains("\"isError\":false"));
+    }
+}
diff --git a/src/mcp/transport.rs b/src/mcp/transport.rs
new file mode 100644
index 000000000..6001a6451
--- /dev/null
+++ b/src/mcp/transport.rs
@@ -0,0 +1,65 @@
+use anyhow::{Context, Result};
+use std::io::{BufRead, BufReader, Write};
+
+pub struct Transport {
+    reader: BufReader<std::io::Stdin>,
+}
+
+impl Transport {
+    pub fn new() -> Self {
+        Self {
+            reader: BufReader::new(std::io::stdin()),
+        }
+    }
+
+    /// Read one newline-terminated JSON line. Returns `None` on EOF.
+    pub fn read_line(&mut self) -> Result<Option<String>> {
+        let mut line = String::new();
+        let n = self
+            .reader
+            .read_line(&mut line)
+            .context("reading from stdin")?;
+        if n == 0 {
+            return Ok(None);
+        }
+        // Strip trailing CR/LF
+        let trimmed = line.trim_end_matches(['\n', '\r']).to_string();
+        Ok(Some(trimmed))
+    }
+
+    /// Write one JSON line to stdout and flush immediately.
+    pub fn write_response(&self, json: &str) -> Result<()> {
+        let mut out = std::io::stdout().lock();
+        out.write_all(json.as_bytes())
+            .context("writing to stdout")?;
+        out.write_all(b"\n").context("writing newline")?;
+        out.flush().context("flushing stdout")?;
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    // Transport uses real stdin/stdout so unit tests cover the helpers.
+
+    #[test]
+    fn test_trim_crlf() {
+        let line = "hello\r\n";
+        let trimmed = line.trim_end_matches(['\n', '\r']);
+        assert_eq!(trimmed, "hello");
+    }
+
+    #[test]
+    fn test_trim_lf_only() {
+        let line = "hello\n";
+        let trimmed = line.trim_end_matches(['\n', '\r']);
+        assert_eq!(trimmed, "hello");
+    }
+
+    #[test]
+    fn test_trim_no_newline() {
+        let line = "hello";
+        let trimmed = line.trim_end_matches(['\n', '\r']);
+        assert_eq!(trimmed, "hello");
+    }
+}
diff --git a/tests/mcp_integration.rs b/tests/mcp_integration.rs
new file mode 100644
index 000000000..084af1189
--- /dev/null
+++ b/tests/mcp_integration.rs
@@ -0,0 +1,292 @@
+//! MCP integration tests.
+//!
+//! These tests spawn the real `rtk mcp-serve` binary and exercise the full
+//! JSON-RPC handshake over stdin/stdout pipes.
+//!
+//! Run with: cargo test --test mcp_integration -- --ignored
+//!
+//! Requirements:
+//!   - RTK binary compiled: `cargo build --release`
+//!   - The binary is located at `target/release/rtk` (or debug)
+
+use std::io::{BufRead, BufReader, Write};
+use std::process::{Child, ChildStdin, ChildStdout, Command, Stdio};
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+fn rtk_binary() -> std::path::PathBuf {
+    // Prefer release build for speed; fall back to debug
+    let release = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("target/release/rtk");
+    let debug = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("target/debug/rtk");
+    if release.exists() {
+        release
+    } else {
+        debug
+    }
+}
+
+struct McpProcess {
+    child: Child,
+    stdin: ChildStdin,
+    reader: BufReader<ChildStdout>,
+}
+
+impl McpProcess {
+    fn spawn() -> Self {
+        let mut child = Command::new(rtk_binary())
+            .arg("mcp-serve")
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::null())
+            .spawn()
+            .expect("Failed to spawn rtk mcp-serve");
+
+        let stdin = child.stdin.take().expect("stdin");
+        let stdout = child.stdout.take().expect("stdout");
+        Self {
+            child,
+            stdin,
+            reader: BufReader::new(stdout),
+        }
+    }
+
+    fn send(&mut self, line: &str) {
+        self.stdin
+            .write_all(line.as_bytes())
+            .expect("write to mcp-serve stdin");
+        self.stdin.write_all(b"\n").expect("write newline");
+        self.stdin.flush().expect("flush stdin");
+    }
+
+    fn recv(&mut self) -> serde_json::Value {
+        let mut line = String::new();
+        self.reader
+            .read_line(&mut line)
+            .expect("read from mcp-serve stdout");
+        serde_json::from_str(line.trim()).expect("parse JSON response")
+    }
+
+    fn send_recv(&mut self, line: &str) -> serde_json::Value {
+        self.send(line);
+        self.recv()
+    }
+}
+
+impl Drop for McpProcess {
+    fn drop(&mut self) {
+        let _ = self.child.kill();
+        let _ = self.child.wait();
+    }
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+#[test]
+#[ignore]
+fn test_initialize_handshake() {
+    let mut proc = McpProcess::spawn();
+
+    let resp = proc.send_recv(
+        r#"{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}},"id":1}"#,
+    );
+
+    assert_eq!(resp["jsonrpc"].as_str().unwrap(), "2.0");
+    assert_eq!(resp["id"].as_i64().unwrap(), 1);
+    assert!(resp["result"].is_object(), "expected result object");
+    assert_eq!(
+        resp["result"]["protocolVersion"].as_str().unwrap(),
+        "2024-11-05"
+    );
+    assert_eq!(
+        resp["result"]["serverInfo"]["name"].as_str().unwrap(),
+        "rtk"
+    );
+}
+
+#[test]
+#[ignore]
+fn test_tools_list_returns_bash() {
+    let mut proc = McpProcess::spawn();
+
+    // Initialize first
+    proc.send_recv(r#"{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}"#);
+
+    let resp = proc.send_recv(r#"{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}"#);
+
+    assert!(resp["result"].is_object());
+    let tools = resp["result"]["tools"].as_array().expect("tools array");
+    assert!(!tools.is_empty(), "expected at least one tool");
+    assert_eq!(tools[0]["name"].as_str().unwrap(), "bash");
+
+    let schema = &tools[0]["inputSchema"];
+    assert_eq!(schema["type"].as_str().unwrap(), "object");
+    assert!(
+        schema["properties"]["command"].is_object(),
+        "command property missing"
+    );
+}
+
+#[test]
+#[ignore]
+fn test_tools_call_bash_echo() {
+    let mut proc = McpProcess::spawn();
+    proc.send_recv(r#"{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}"#);
+
+    let resp = proc.send_recv(
+        r#"{"jsonrpc":"2.0","method":"tools/call","params":{"name":"bash","arguments":{"command":"echo rtk_mcp_ok"}},"id":3}"#,
+    );
+
+    assert!(
+        resp.get("result").is_some(),
+        "expected result, got: {}",
+        resp
+    );
+    assert_eq!(resp["result"]["isError"].as_bool(), Some(false));
+    let text = resp["result"]["content"][0]["text"].as_str().unwrap_or("");
+    assert!(
+        text.contains("rtk_mcp_ok"),
+        "expected echo output in: {:?}",
+        text
+    );
+}
+
+#[test]
+#[ignore]
+fn test_tools_call_bash_git_status() {
+    let mut proc = McpProcess::spawn();
+    proc.send_recv(r#"{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}"#);
+
+    let resp = proc.send_recv(
+        r#"{"jsonrpc":"2.0","method":"tools/call","params":{"name":"bash","arguments":{"command":"git status"}},"id":4}"#,
+    );
+
+    assert!(
+        resp.get("result").is_some(),
+        "expected result, got: {}",
+        resp
+    );
+    // git status in the rtk repo should succeed
+    assert_eq!(
+        resp["result"]["isError"].as_bool(),
+        Some(false),
+        "git status failed unexpectedly: {}",
+        resp
+    );
+    let text = resp["result"]["content"][0]["text"].as_str().unwrap_or("");
+    assert!(!text.is_empty(), "expected non-empty git status output");
+}
+
+#[test]
+#[ignore]
+fn test_tools_call_bash_filters_git_output() {
+    let mut proc = McpProcess::spawn();
+    proc.send_recv(r#"{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}"#);
+
+    let resp = proc.send_recv(
+        r#"{"jsonrpc":"2.0","method":"tools/call","params":{"name":"bash","arguments":{"command":"git log -5"}},"id":5}"#,
+    );
+
+    assert!(resp.get("result").is_some());
+    let text = resp["result"]["content"][0]["text"].as_str().unwrap_or("");
+    // RTK git log filter produces compact output — verify it's shorter than raw git log
+    // (raw git log -5 would be at minimum 5 * ~6 lines = 30 lines; RTK compacts to 5 lines)
+    let line_count = text.lines().count();
+    assert!(line_count > 0, "expected some output from git log");
+    assert!(
+        line_count <= 20,
+        "expected RTK to compact git log (got {} lines, expected ≤20)",
+        line_count
+    );
+}
+
+#[test]
+#[ignore]
+fn test_tools_call_failing_command_is_error() {
+    let mut proc = McpProcess::spawn();
+    proc.send_recv(r#"{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}"#);
+
+    // A command that always fails
+    let resp = proc.send_recv(
+        r#"{"jsonrpc":"2.0","method":"tools/call","params":{"name":"bash","arguments":{"command":"sh -c 'exit 42'"}},"id":6}"#,
+    );
+
+    assert!(resp.get("result").is_some());
+    assert_eq!(
+        resp["result"]["isError"].as_bool(),
+        Some(true),
+        "expected isError=true for failing command"
+    );
+}
+
+#[test]
+#[ignore]
+fn test_unknown_method_returns_error() {
+    let mut proc = McpProcess::spawn();
+    proc.send_recv(r#"{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}"#);
+
+    let resp =
+        proc.send_recv(r#"{"jsonrpc":"2.0","method":"nonexistent/method","params":{},"id":7}"#);
+
+    assert!(resp["error"].is_object(), "expected error object");
+    assert_eq!(resp["error"]["code"].as_i64().unwrap(), -32601);
+}
+
+#[test]
+#[ignore]
+fn test_parse_error_returns_error() {
+    let mut proc = McpProcess::spawn();
+
+    let resp = proc.send_recv("this is not json {{{");
+    assert!(resp["error"].is_object(), "expected parse error");
+    assert_eq!(resp["error"]["code"].as_i64().unwrap(), -32700);
+}
+
+#[test]
+#[ignore]
+fn test_notification_receives_no_response() {
+    let mut proc = McpProcess::spawn();
+
+    // Send initialize to get a response
+    proc.send_recv(r#"{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}"#);
+
+    // Send initialized notification (no id) — must get NO response
+    proc.send(r#"{"jsonrpc":"2.0","method":"initialized","params":{}}"#);
+
+    // Send ping — should get a response (proves server is still alive)
+    let resp = proc.send_recv(r#"{"jsonrpc":"2.0","method":"ping","params":{},"id":2}"#);
+    assert!(resp["result"].is_object(), "ping should return result");
+}
+
+#[test]
+#[ignore]
+fn test_multiple_sequential_calls() {
+    let mut proc = McpProcess::spawn();
+    proc.send_recv(r#"{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}"#);
+
+    // Run 3 commands sequentially, verify ids are preserved
+    for i in 2..=4 {
+        let req = format!(
+            r#"{{"jsonrpc":"2.0","method":"tools/call","params":{{"name":"bash","arguments":{{"command":"echo seq_{}"}}}},"id":{}}}"#,
+            i, i
+        );
+        let resp = proc.send_recv(&req);
+        assert_eq!(resp["id"].as_i64().unwrap(), i as i64);
+        let text = resp["result"]["content"][0]["text"].as_str().unwrap_or("");
+        assert!(text.contains(&format!("seq_{}", i)));
+    }
+}
+
+#[test]
+#[ignore]
+fn test_shutdown_cleanly_closes_server() {
+    let mut proc = McpProcess::spawn();
+    proc.send_recv(r#"{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}"#);
+
+    let resp = proc.send_recv(r#"{"jsonrpc":"2.0","method":"shutdown","params":{},"id":99}"#);
+    assert!(resp["result"].is_object());
+
+    // After shutdown, reading from stdout should yield EOF
+    let mut line = String::new();
+    let n = proc.reader.read_line(&mut line).unwrap_or(0);
+    assert_eq!(n, 0, "expected EOF after shutdown");
+}

From eb2ddfc6612bece2395f53da2cd9f363ceb30f3e Mon Sep 17 00:00:00 2001
From: CI <test@ci.com>
Date: Fri, 17 Apr 2026 20:27:44 +0400
Subject: [PATCH 3/4] fix(mcp): shell-fallback on exit 127 + fix shutdown test
 assertion

On Windows, shell builtins (echo, dir, etc.) have no standalone binary.
RTK's run_fallback returns exit 127 when the binary isn't found. The MCP
handler now retries via `cmd /C` when RTK exits 127, making builtins
and compound expressions work cross-platform.

Also fix test_shutdown_cleanly_closes_server: shutdown returns
{"result":null} which is not is_object(); check absence of "error" instead.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/mcp/handler.rs       | 7 +++++++
 tests/mcp_integration.rs | 3 ++-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/mcp/handler.rs b/src/mcp/handler.rs
index 8df47056e..eb3c933de 100644
--- a/src/mcp/handler.rs
+++ b/src/mcp/handler.rs
@@ -146,6 +146,13 @@ fn run_with_rtk_binary(command: &str) -> (String, i32) {
             let stdout = String::from_utf8_lossy(&output.stdout).into_owned();
             let stderr = String::from_utf8_lossy(&output.stderr).into_owned();
             let combined = merge_output(stdout, stderr);
+
+            // Exit 127 = command not found by RTK's fallback (e.g., shell builtins on Windows).
+            // Retry via system shell so `echo`, `dir`, compound expressions, etc. work correctly.
+            if exit_code == 127 {
+                return run_raw_shell(command);
+            }
+
             (combined, exit_code)
         }
         Err(e) => {
diff --git a/tests/mcp_integration.rs b/tests/mcp_integration.rs
index 084af1189..53a363e50 100644
--- a/tests/mcp_integration.rs
+++ b/tests/mcp_integration.rs
@@ -283,7 +283,8 @@ fn test_shutdown_cleanly_closes_server() {
     proc.send_recv(r#"{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}"#);
 
     let resp = proc.send_recv(r#"{"jsonrpc":"2.0","method":"shutdown","params":{},"id":99}"#);
-    assert!(resp["result"].is_object());
+    // shutdown returns null result (not an object) — just verify no error
+    assert!(resp.get("error").is_none(), "shutdown returned error: {}", resp);
 
     // After shutdown, reading from stdout should yield EOF
     let mut line = String::new();

From 44c8addd736097a1abff33eb9afdc888bc29e59e Mon Sep 17 00:00:00 2001
From: CI <test@ci.com>
Date: Fri, 17 Apr 2026 21:14:42 +0400
Subject: [PATCH 4/4] docs: add Claude Desktop MCP section to README

- Add Claude Desktop row to Supported AI Tools table
- Add Claude Desktop (MCP) section with setup steps, architecture
  diagram, manual config instructions, and link to docs/MCP.md
- Add Claude Desktop nav link in header
- Add docs/MCP.md to Documentation section

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/README.md b/README.md
index 6228a689d..9c45c2bc7 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,7 @@
 <p align="center">
   <a href="https://www.rtk-ai.app">Website</a> &bull;
   <a href="#installation">Install</a> &bull;
+  <a href="#claude-desktop-mcp">Claude Desktop</a> &bull;
   <a href="https://www.rtk-ai.app/guide/troubleshooting">Troubleshooting</a> &bull;
   <a href="ARCHITECTURE.md">Architecture</a> &bull;
   <a href="https://discord.gg/RySmvNF5kF">Discord</a>
@@ -311,6 +312,49 @@ rtk init --show             # Verify installation
 
 After install, **restart Claude Code**.
 
+## Claude Desktop (MCP)
+
+RTK works with **Claude Desktop** via the [Model Context Protocol](https://modelcontextprotocol.io). It exposes a `bash` tool that routes commands through the same filter pipeline used by Claude Code hooks — the same 60-90% token savings, no configuration needed per-project.
+
+```bash
+rtk mcp-install   # Register RTK in Claude Desktop's config, then restart the app
+```
+
+That's it. After restarting Claude Desktop, RTK's `bash` tool appears in the tool picker and all shell commands it runs go through RTK's filters automatically.
+
+**How it works:**
+
+```
+Claude Desktop → bash tool call {command: "git log -10"}
+                      ↓
+              rtk mcp-serve (stdio JSON-RPC 2.0, <10ms startup)
+                      ↓
+              spawns: rtk git log -10  (applies git log filter)
+                      ↓
+              returns compact output to Claude Desktop (~80% fewer tokens)
+```
+
+**Manual install** (if `rtk mcp-install` doesn't detect your config path):
+
+| Platform | Config file |
+|----------|-------------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+
+```json
+{
+  "mcpServers": {
+    "rtk": {
+      "command": "/full/path/to/rtk",
+      "args": ["mcp-serve"]
+    }
+  }
+}
+```
+
+MCP-sourced savings appear in `rtk gain --history` under `source=mcp`. See [docs/MCP.md](docs/MCP.md) for full setup, verification, and troubleshooting.
+
 ## Windows
 
 RTK works on Windows with some limitations. The auto-rewrite hook (`rtk-rewrite.sh`) requires a Unix shell, so on native Windows RTK falls back to **CLAUDE.md injection mode** — your AI assistant receives RTK instructions but commands are not rewritten automatically.
@@ -355,6 +399,7 @@ RTK supports 12 AI coding tools. Each integration transparently rewrites shell c
 | Tool | Install | Method |
 |------|---------|--------|
 | **Claude Code** | `rtk init -g` | PreToolUse hook (bash) |
+| **Claude Desktop** | `rtk mcp-install` | MCP server (`bash` tool) |
 | **GitHub Copilot (VS Code)** | `rtk init -g --copilot` | PreToolUse hook — transparent rewrite |
 | **GitHub Copilot CLI** | `rtk init -g --copilot` | PreToolUse deny-with-suggestion (CLI limitation) |
 | **Cursor** | `rtk init -g --agent cursor` | preToolUse hook (hooks.json) |
@@ -403,6 +448,7 @@ brew uninstall rtk           # If installed via Homebrew
 ## Documentation
 
 - **[rtk-ai.app/guide](https://www.rtk-ai.app/guide)** — full user guide (installation, supported agents, what gets optimized, analytics, configuration, troubleshooting)
+- **[docs/MCP.md](docs/MCP.md)** — Claude Desktop MCP server setup, verification, troubleshooting
 - **[INSTALL.md](INSTALL.md)** — detailed installation reference
 - **[ARCHITECTURE.md](ARCHITECTURE.md)** — system design and technical decisions
 - **[CONTRIBUTING.md](CONTRIBUTING.md)** — contribution guide