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

Setup Instructions

1. Install Dependencies

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:

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

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]:

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:

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!