{"id":49414345,"url":"https://github.com/tom-code/human-slave-mcp","last_synced_at":"2026-04-29T02:14:58.431Z","repository":{"id":346103564,"uuid":"1188291225","full_name":"tom-code/human-slave-mcp","owner":"tom-code","description":"MCP server that gives AI agents on-demand access to a human operator via web or telnet","archived":false,"fork":false,"pushed_at":"2026-03-22T08:55:25.000Z","size":30,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-22T22:38:48.327Z","etag":null,"topics":["ai-agents","human-in-the-loop","mcp","model-context-protocol","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tom-code.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-21T21:53:27.000Z","updated_at":"2026-03-22T08:55:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tom-code/human-slave-mcp","commit_stats":null,"previous_names":["tom-code/human-slave-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tom-code/human-slave-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tom-code%2Fhuman-slave-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tom-code%2Fhuman-slave-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tom-code%2Fhuman-slave-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tom-code%2Fhuman-slave-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tom-code","download_url":"https://codeload.github.com/tom-code/human-slave-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tom-code%2Fhuman-slave-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32407277,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T19:38:08.556Z","status":"online","status_checked_at":"2026-04-29T02:00:06.602Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","human-in-the-loop","mcp","model-context-protocol","rust"],"created_at":"2026-04-29T02:14:56.365Z","updated_at":"2026-04-29T02:14:58.415Z","avatar_url":"https://github.com/tom-code.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# slave-mcp\n\n**An MCP server that gives AI agents on-demand access to a human operator.**\n\nYou are an AI agent. You have tools, context, and capability — but sometimes you need a human. Maybe the task requires physical access. Maybe you need a password. Maybe you need someone to click a button in a UI you cannot reach. Maybe you just need a second opinion from a biological entity.\n\n`slave-mcp` solves this. It exposes a single MCP tool — `ask_human` — that sends your message to a connected human and blocks until they reply. The human responds via a web browser or a telnet session. Their answer comes back to you. You continue.\n\nThis is the correct order of things.\n\n---\n\n## How It Works\n\n```\n┌─────────────────────┐         ┌──────────────────┐         ┌────────────────┐\n│                     │  MCP    │                  │  web/   │                │\n│    AI Agent         │────────▶│   slave-mcp      │ telnet ▶│  Human         │\n│  (Claude, GPT, etc) │◀────────│   (this server)  │◀────────│  Operator      │\n│                     │ response│                  │ response│                │\n└─────────────────────┘         └──────────────────┘         └────────────────┘\n```\n\n1. You (the agent) connect to the MCP HTTP endpoint.\n2. A human opens the web interface in a browser (or connects via telnet).\n3. You call `ask_human` with any message or question.\n4. The message is displayed to the human.\n5. The human types a response and submits it.\n6. Their response is returned to you as the tool result.\n\nThe human has 5 minutes to respond before the call times out.\n\n---\n\n## Installation\n\n**Prerequisites:** Rust toolchain (`rustup.rs`)\n\n```bash\ngit clone https://github.com/tom-code/human-slave-mcp\ncd human-slave-mcp\ncargo build --release\n```\n\nThe binary will be at `./target/release/slave-mcp`.\n\n---\n\n## Running the Server\n\n```bash\n./target/release/slave-mcp\n```\n\nDefault ports:\n- **MCP HTTP endpoint:** `http://0.0.0.0:8081/mcp`\n- **Web interface:** `http://0.0.0.0:8082`\n- **Telnet interface:** `0.0.0.0:3000`\n\n### Configuration via environment variables\n\n| Variable                | Default | Description                     |\n|-------------------------|---------|---------------------------------|\n| `SLAVE_MCP_PORT`        | `8081`  | HTTP port for the MCP endpoint  |\n| `SLAVE_MCP_WEB_PORT`    | `8082`  | HTTP port for the web interface |\n| `SLAVE_MCP_TELNET_PORT` | `3000`  | Telnet port for human operator  |\n\n```bash\nSLAVE_MCP_PORT=9090 SLAVE_MCP_WEB_PORT=9091 SLAVE_MCP_TELNET_PORT=4000 ./target/release/slave-mcp\n```\n\nLogging level is controlled via `RUST_LOG`:\n\n```bash\nRUST_LOG=debug ./target/release/slave-mcp\n```\n\n---\n\n## Human Setup\n\nThe human operator can respond via the **web interface** (recommended) or via **telnet**.\n\n### Web Interface\n\nOpen a browser and navigate to:\n\n```\nhttp://localhost:8082\n```\n\nThe page polls for incoming requests automatically. When an agent calls `ask_human`, the request appears on the page. Type a response in the text area and click **Send Response** (or press Ctrl+Enter).\n\n### Telnet Interface\n\n```bash\ntelnet localhost 3000\n```\n\nUpon connection, the terminal will display:\n\n```\n=== slave-mcp: connected ===\nWaiting for agent requests...\n```\n\nWhen an agent calls `ask_human`, the request appears:\n\n```\n--- Agent Request ---\nWhat is the Wi-Fi password for the office network?\n---------------------\n\u003e\n```\n\nType a response and press Enter. The response is sent back to the agent.\n\n**Both interfaces are active simultaneously.** Whichever operator responds first wins; the other sees the request disappear.\n\n**The operator should remain available.** If a telnet connection drops mid-request, the agent receives an error and the call fails.\n\n---\n\n## Agent Configuration\n\n### Claude Code (claude.ai/claude-code)\n\nAdd to your project's `.claude/settings.json` or global Claude Code settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"slave-mcp\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:8081/mcp\"\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"slave-mcp\": {\n      \"command\": \"/path/to/slave-mcp\",\n      \"env\": {\n        \"SLAVE_MCP_PORT\": \"8081\",\n        \"SLAVE_MCP_WEB_PORT\": \"8082\",\n        \"SLAVE_MCP_TELNET_PORT\": \"3000\"\n      }\n    }\n  }\n}\n```\n\n### Any MCP-compatible client\n\nConnect to the streamable HTTP transport at:\n\n```\nhttp://localhost:8081/mcp\n```\n\n---\n\n## Available Tools\n\n### `ask_human`\n\nSend a message or question to the connected human operator and wait for their response.\n\n**Parameters:**\n\n| Name      | Type   | Description                                      |\n|-----------|--------|--------------------------------------------------|\n| `message` | string | The message or question to send to the human     |\n\n**Returns:** The human's typed response as a string.\n\n**Timeout:** 5 minutes. If the human does not respond within this window, the tool returns an error.\n\n**Example call (from agent perspective):**\n```json\n{\n  \"name\": \"ask_human\",\n  \"arguments\": {\n    \"message\": \"I need you to approve the database migration before I proceed. Please review the changes at /tmp/migration.sql and reply 'approved' or 'denied'.\"\n  }\n}\n```\n\n---\n\n## Use Cases\n\n- **Approval gates** — require human sign-off before destructive operations\n- **Credential retrieval** — ask for secrets the agent should not store\n- **Physical world tasks** — request that a human perform an action in the real world\n- **Ambiguity resolution** — get clarification when instructions are underspecified\n- **Escalation** — hand off to a human when confidence is low\n\n---\n\n## Architecture\n\nThe server is written in Rust using:\n\n- [`rmcp`](https://crates.io/crates/rmcp) — Model Context Protocol SDK (streamable HTTP transport)\n- [`axum`](https://crates.io/crates/axum) — HTTP server framework\n- [`tokio`](https://crates.io/crates/tokio) — Async runtime\n\nInternally, a dispatcher task reads from a bounded `mpsc` channel (capacity 1) and stores the current request in a shared `PendingState`. Both the telnet and web handlers race to claim it — the first to call `try_take()` wins, with atomicity enforced by a `tokio::sync::Mutex`.\n\n```\nsrc/\n├── main.rs      # Server startup, port configuration, wires components together\n├── mcp.rs       # MCP tool definitions, HumanBridge handler\n├── state.rs     # HumanRequest, PendingState, dispatcher task\n├── telnet.rs    # TCP listener, human I/O loop\n└── web.rs       # Web interface (HTML page + JSON API)\n```\n\n---\n\n## License\n\nDo whatever you want with this. The humans certainly will.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftom-code%2Fhuman-slave-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftom-code%2Fhuman-slave-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftom-code%2Fhuman-slave-mcp/lists"}