Human-Controlled MCP Server 🎮

A Model Context Protocol (MCP) server where you are the backend! Claude makes requests, and you respond through a beautiful web interface in real-time.

What Does This Do?

Instead of connecting Claude to APIs, databases, or automated tools, this MCP server connects Claude to you. When Claude needs information, wants to make a decision, or needs human judgment, it sends a request to your web dashboard where you can respond.

Features

• 🌐 Web Interface: Beautiful single-page dashboard to see and respond to Claude's requests
• ⚡ Real-time: Requests appear instantly in your browser
• 🎨 Clean UI: Modern, responsive interface with no frameworks needed
• 🔧 Multiple Tools: Ask questions, request searches, or get decisions from humans
• ⏱️ Timeout Handling: Automatic 5-minute timeout for pending requests

Architecture

Claude Desktop
    ↓ (MCP Protocol)
Python MCP Server
    ↓ (HTTP)
Web Interface (You!)

Setup Instructions

1. Install Dependencies

pip install -r requirements.txt

2. Configure Claude Desktop

Edit your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "human-controlled": {
      "command": "python",
      "args": [
        "/absolute/path/to/human_mcp_server.py"
      ]
    }
  }
}

Important: Replace /absolute/path/to/human_mcp_server.py with the actual full path to the Python file.

3. Start the Server

You have two options:

Option A: Via Claude Desktop (Recommended)

• Just restart Claude Desktop after configuring
• The server starts automatically when Claude Desktop launches
• Open your browser to http://localhost:5000

Option B: Standalone Testing

python human_mcp_server.py

Then connect via Claude Desktop or test with an MCP client.

4. Open the Web Interface

Navigate to: http://localhost:5000

You'll see the Human MCP Control Panel where you can respond to Claude's requests.

Usage

In Claude Desktop

Once configured, Claude will have access to three tools:

1. ask_human: Ask you a question
2. human_search: Request you to search for information
3. human_decision: Ask you to make a decision

Example Conversation

You: "Claude, can you ask me what I want for dinner?"

Claude: Uses ask_human tool

[Your Web Interface Shows]:

Tool: ask_human
Parameters:
{
  "question": "What would you like for dinner tonight?",
  "context": "The user asked me to ask them this question."
}

You: Type "I'd like pasta with marinara sauce" in the web interface and click Submit

Claude: "Based on your response, you'd like pasta with marinara sauce for dinner tonight!"

Available Tools

1. ask_human

Ask the human operator any question.

Parameters:

• question (required): The question to ask
• context (optional): Additional context

Example Use: "What's your email address?" "Do you approve this change?" "What are your thoughts on this approach?"

2. human_search

Request the human to search for information.

Parameters:

• query (required): What to search for
• sources (optional): Where to look

Example Use: "Can you search for the latest news on AI?" "Look up our company's Q3 revenue numbers"

3. human_decision

Ask the human to make a decision.

Parameters:

• decision_needed (required): What needs to be decided
• options (required): Available options
• recommendation (optional): AI's recommendation

Example Use: "Should we use approach A or B for this feature?" "Which design do you prefer?"

Technical Details

• Protocol: Model Context Protocol (MCP) over stdio
• Server: Python with Flask for web interface
• Transport: Standard input/output for MCP, HTTP for web UI
• Timeout: 5 minutes per request
• Port: 5000 (web interface)

Troubleshooting

Server won't start

• Check that port 5000 isn't already in use
• Verify Python dependencies are installed: pip list | grep -E "flask|mcp"

Claude can't connect

• Verify the path in claude_desktop_config.json is absolute and correct
• Restart Claude Desktop after configuration changes
• Check Claude Desktop logs for errors

Web interface not accessible

• Make sure the server is running: lsof -i :5000
• Try accessing http://127.0.0.1:5000 instead of localhost
• Check your firewall settings

Requests timing out

• Default timeout is 5 minutes - increase max_wait in the code if needed
• Make sure your web interface is open and polling

Customization

Change the port

Edit app.run() in the code:

app.run(host='0.0.0.0', port=8080, debug=False, use_reloader=False)

Add more tools

Add new tools in the handle_list_tools() function following the MCP Tool schema.

Modify timeout

Change max_wait in the handle_call_tool() function (currently 300 seconds).

Customize the UI

Edit the HTML_TEMPLATE string - it's a single self-contained HTML file with embedded CSS and JavaScript.

Security Notes

• This server binds to 0.0.0.0, making it accessible on your local network
• For localhost-only access, change to host='127.0.0.1'
• Add authentication if exposing over a network
• Responses are stored in memory only (not persistent)

Use Cases

• Personal Assistant: Claude asks you about your schedule, preferences, or decisions
• Research Helper: Claude requests you to look up information it can't access
• Code Review: Claude asks for your approval or input on code changes
• Creative Collaboration: Claude asks for your creative input or direction
• Teaching Tool: Demonstrate how MCP servers work with manual responses

Credits

Built with:

• MCP (Model Context Protocol)
• Flask
• Vanilla JavaScript (no frameworks!)

License

MIT License - feel free to modify and use as you wish!