IN
Developer Tools

Interactive MCP Server: Local Cross-Platform Human-in-the-Loop Agent

Run a local cross-platform MCP server to interact with your human-in-the-loop AI agent for real-time collaborative coding and feedback.

View on GitHub
Quick Install
npx -y @ttommyth/interactive-mcp

Overview

Interactive MCP Server is a small, cross-platform server that implements the Model Context Protocol (MCP) to enable human-in-the-loop AI agents for real-time collaboration. Run locally on your machine or in a private network to let an AI agent coordinate with humans and tools during tasks such as pair programming, iterative code review, or stepwise debugging. Because it runs locally and exposes lightweight protocol endpoints, it is suitable for scenarios where latency, privacy, or offline operation matter.

The server acts as a coordinator between model clients, developer tools, and human participants. It provides an API and realtime channels for sending and receiving MCP messages, managing context, and attaching tool integrations (editors, terminals, test runners). Developers can use it to prototype interactive agent workflows or to integrate an explicit human feedback loop into automated processes.

Features

  • Local and cross-platform — runs on macOS, Linux, and Windows.
  • MCP-compatible API — supports message exchanges that follow the Model Context Protocol.
  • Realtime channels — WebSocket endpoints for low-latency human-agent interactions.
  • Human-in-the-loop coordination — pause/resume, ask-for-clarification, and accept/reject flows.
  • Tool integration hooks — attach editors, linters, test runners, or other local tools.
  • Simple configuration — environment variables or JSON/YAML config files.
  • Authentication and optional TLS for private deployments.
  • Logging and observability endpoints for debugging and monitoring.

Installation / Configuration

Prerequisites: Git and a recent Node.js (or Python) runtime depending on repository language. The examples below use a typical Node.js workflow.

  1. Clone the repo:
git clone https://github.com/ttommyth/interactive-mcp.git
cd interactive-mcp
  1. Install dependencies:
# Node.js example
npm install
# or, if the project uses yarn
yarn install
  1. Create a basic configuration (env or JSON). Example environment variables:
# .env
MCP_HOST=127.0.0.1
MCP_PORT=3000
MCP_ALLOW_REMOTE=false
MCP_AUTH_TOKEN=change-me
MCP_TLS=false

Or use a config file (config.json):

{
  "host": "127.0.0.1",
  "port": 3000,
  "allowRemote": false,
  "authToken": "change-me",
  "tls": false,
  "toolHooks": {
    "editor": true,
    "tests": true
  }
}
  1. Start the server:
# Node.js
npm run start

# or directly
node server.js --config=config.json
  1. Verify the server is running:
curl -H "Authorization: Bearer change-me" http://127.0.0.1:3000/status

Notes:

  • For production or networked use, enable TLS and change the auth token.
  • Use the CLI --help to discover runtime options exposed by the repository.

Available Resources

The server typically exposes the following resources (adjust paths/ports according to your local config):

  • REST endpoints
    • /status or /health — basic health checks
    • /sessions — create/manage interactive sessions
    • /tools — register or query tool integrations
  • WebSocket/MCP endpoint
    • /mcp or /ws — realtime MCP message channel for model and human clients
  • Web UI (optional)
    • A small browser UI for human participants to view the agent context, send clarifications, and accept changes
  • Logs and observability
    • Local log files or debug endpoints to trace message flows and tool activity
  • Tool hooks
    • Integration endpoints or scripts to run local commands (tests, linters, code generation)

Use the server’s documentation or the --help output to get exact route names and payload shapes.

Use Cases

  • Pair programming with an AI agent:
    • Start a session, attach your editor tool hook, ask the agent to propose a refactor. The agent posts a diff; you review and accept or request clarification before applying changes to the codebase.
  • Interactive code review:
    • Run tests and have the agent suggest fixes. Human reviewers inspect suggestions and give approval, creating a tight feedback loop that speeds up iterations.
  • Teaching and mentorship:
    • Instructors create scenarios where students ask the agent step-by-step questions; instructors can interject, correct, and steer the session in real time.
  • Debugging and repro steps:
    • The agent collects context, proposes hypotheses, and requests additional logs or commands. Humans provide the requested artifacts and the agent refines its reasoning.

Quick Start Example (WebSocket)

Connect to the realtime channel using websocat or a browser client:

# Using websocat
websocat "ws://127.0.0.1:3000/mcp" -H "Authorization: Bearer change-me"

Once connected, exchange MCP-formatted JSON messages representing agent prompts, human clarifications, tool requests, and context updates.

Security and Best Practices

  • Run locally or restrict binding to localhost when working with sensitive data.
  • Rotate authentication tokens and enable TLS for networked use.
  • Limit tool hooks to safe, sandboxed operations where possible.
  • Monitor logs and use rate limiting when exposing the server on shared networks.

For more details and examples, see the repository on GitHub: https://github.com/ttommyth/interactive-mcp

Tags:developer-tools