scottgl9 · scottgl9 · Jan 17, 2026 · Jan 17, 2026 · Jan 17, 2026 · Jan 17, 2026
diff --git a/README.md b/README.md
@@ -8,6 +8,7 @@ A lightweight CLI tool that enables AI agents to execute commands across local a
 - **SSH config integration**: Automatically reads `~/.ssh/config` for host aliases
 - **Context switching**: Switch between sessions with simple slash commands
 - **Proxy mode**: Use as a SHELL for AI agents like Claude Code
+- **MCP server**: Built-in Model Context Protocol server for AI agent integration
 - **State persistence**: Maintains working directory and environment across commands
 - **Shell completions**: Tab completion for bash, zsh, and fish
 
@@ -67,6 +68,16 @@ SHELL="thop --proxy" claude
 echo "ls -la" | thop --proxy
 ```
 
+### MCP Server Mode
+
+```bash
+# Start as MCP server
+thop --mcp
+
+# Configure in Claude Desktop
+# See docs/MCP.md for full configuration
+```
+
 ## Configuration
 
 ### Config File
@@ -285,6 +296,7 @@ With agent forwarding enabled, you can use git over SSH, SSH to other servers, o
 | Flag | Description |
 |------|-------------|
 | `--proxy` | Run in proxy mode (for AI agents) |
+| `--mcp` | Run as MCP server (Model Context Protocol) |
 | `-c <cmd>` | Execute command and exit |
 | `--status` | Show status and exit |
 | `--config <path>` | Use alternate config file |
@@ -304,7 +316,21 @@ With agent forwarding enabled, you can use git over SSH, SSH to other servers, o
 | 2 | Authentication failed |
 | 3 | Host key verification failed |
 
-## Integration with Claude Code
+## Integration with AI Agents
+
+### For Claude Code Users
+
+**Important**: Copy the agent documentation to your project directory:
+
+```bash
+# Copy Claude-specific guide to your project
+cp /path/to/thop/docs/THOP_FOR_CLAUDE.md ~/myproject/
+
+# Or for other AI agents
+cp /path/to/thop/docs/THOP_FOR_AGENTS.md ~/myproject/
+```
+
+This gives Claude complete instructions on how to use thop when working in that project.
 
 To use thop as the shell for Claude Code:
 
@@ -339,6 +365,17 @@ cat /var/log/app.log
 /local
 ```
 
+### Documentation for AI Agents
+
+See the `docs/` directory for comprehensive guides:
+
+- **[docs/THOP_FOR_CLAUDE.md](docs/THOP_FOR_CLAUDE.md)** - Complete guide for Claude Code with workflows and examples
+- **[docs/THOP_FOR_AGENTS.md](docs/THOP_FOR_AGENTS.md)** - Platform-agnostic guide for any AI agent
+- **[docs/MCP.md](docs/MCP.md)** - MCP server integration guide
+- **[docs/AGENT_README.md](docs/AGENT_README.md)** - How to use the agent documentation
+
+**Copy these files to your project directories** so Claude has access to the instructions when working on those projects.
+
 ## State Persistence
 
 thop maintains state in `~/.local/share/thop/state.json`:
@@ -405,6 +442,7 @@ thop-go/
 ├── internal/
 │   ├── cli/           # CLI handling (interactive, proxy, completions)
 │   ├── config/        # Configuration parsing
+│   ├── mcp/           # MCP server implementation
 │   ├── session/       # Session management (local, SSH)
 │   ├── sshconfig/     # SSH config parsing
 │   └── state/         # State persistence

diff --git a/TODO.md b/TODO.md
@@ -172,9 +172,27 @@ After language selection, implement full MVP in chosen language.
 - [x] Async command execution (/bg command)
 - [x] Background command with status polling (/jobs, /fg, /kill commands)
 
+### MCP Server ✅
+- [x] Built-in MCP server mode (--mcp flag)
+- [x] JSON-RPC 2.0 protocol implementation
+- [x] Session management tools (connect, switch, close, status)
+- [x] Command execution tool (execute with timeout/background support)
+- [x] Resources (session, config, state)
+- [x] Comprehensive test coverage (77.1%)
+- [ ] **See docs/MCP_IMPROVEMENTS.md for future enhancements:**
+  - [ ] SSH config auto-discovery (~/.ssh/config, known_hosts)
+  - [ ] Command timeout handling
+  - [ ] Structured error codes
+  - [ ] File transfer tools (SCP upload/download)
+  - [ ] Read-only file operation tools
+  - [ ] Connection health checks and auto-reconnect
+  - [ ] Rate limiting and circuit breakers
+  - [ ] Background job management (full implementation)
+  - [ ] Batch command support
+  - [ ] Sudo/privilege elevation
+
 ### Future
-- [ ] MCP server wrapper
-- [ ] Metrics and observability
+- [ ] Metrics and observability (see MCP_IMPROVEMENTS.md for details)
 
 ---
 

diff --git a/docs/AGENT_README.md b/docs/AGENT_README.md
@@ -0,0 +1,80 @@
+# Agent Documentation for thop
+
+This directory contains documentation specifically designed for AI coding agents (like Claude Code) working within thop sessions.
+
+## Files
+
+### THOP_FOR_AGENTS.md (236 lines)
+**General agent guide** - Platform-agnostic, essential instructions
+
+- Detection and core concepts
+- Essential commands (session, file, env, jobs)
+- 3 workflow examples
+- Best practices and error handling
+- Quick reference table
+- Common pitfalls to avoid
+
+**Use this for**: Any AI agent integration
+
+### THOP_FOR_CLAUDE.md (141 lines)
+**Claude-specific guide** - Concise, focused instructions
+
+- Quick detection method
+- Core commands with examples
+- 1 complete workflow example
+- Common patterns (debug, compare, deploy)
+- Best practices summary
+- Quick reference table
+
+**Use this for**: Claude Code, Claude Desktop, claude.vim
+
+## How to Use These Docs
+
+**Copy to your project directory** so AI agents have access when working on that project:
+
+```bash
+# For Claude Code
+cp /path/to/thop/docs/THOP_FOR_CLAUDE.md ~/myproject/
+
+# For other AI agents
+cp /path/to/thop/docs/THOP_FOR_AGENTS.md ~/myproject/
+```
+
+Then reference in your project README:
+
+```markdown
+## AI Agent Setup
+
+This project uses thop for remote server management.
+
+See [THOP_FOR_CLAUDE.md](./THOP_FOR_CLAUDE.md) for usage instructions.
+```
+
+## Why These Docs Were Simplified
+
+Original versions were 730+ lines with extensive examples. We've distilled them to essentials:
+
+- **Focus on what agents need to know**, not comprehensive documentation
+- **Core commands and common patterns** instead of exhaustive examples
+- **Quick reference format** for fast lookups
+- **Reduced token usage** when agents read these files
+
+Full documentation is in the main README.md and other docs.
+
+## What's Included
+
+Both docs cover essentials:
+- ✅ Session detection (`$THOP_SESSION`)
+- ✅ Core commands (`/status`, `/connect`, `/switch`, `/copy`)
+- ✅ Workflow examples (deploy, debug, compare)
+- ✅ Error handling (AUTH_KEY_FAILED, etc.)
+- ✅ Best practices (always check `/status`, return to `/local`)
+- ✅ Quick reference tables
+
+---
+
+**Quick Links**:
+- [THOP_FOR_AGENTS.md](./THOP_FOR_AGENTS.md) - General agent guide
+- [THOP_FOR_CLAUDE.md](./THOP_FOR_CLAUDE.md) - Claude-specific guide
+- [MCP.md](./MCP.md) - MCP server documentation
+- [MCP_IMPROVEMENTS.md](./MCP_IMPROVEMENTS.md) - Planned MCP enhancements