Hostaway MCP Server

# Claude Desktop Connection - Debugging Summary ## Problem Identified **Error**: "Server disconnected" in Claude Desktop when connecting to hostaway-mcp **Root Causes** (Fixed in sequence): 1. ✅ **SSE Transport Issue**: FastAPI-MCP uses HTTP/SSE transport, but Claude Desktop requires stdio-based MCP servers 2. ✅ **PATH Issue**: Claude Desktop cannot find `uv` command - not in its PATH (`spawn uv ENOENT` error) ## Solution Implemented Created a **native MCP stdio server** (`mcp_stdio_server.py`) that: - Uses the official MCP Python SDK - Communicates via stdio (compatible with Claude Desktop) - Makes HTTP calls to the FastAPI REST API (localhost:8000) - Properly implements the MCP protocol initialization sequence ## Architecture Change ### Before (Failed): ``` Claude Desktop → mcp_stdio_bridge.py → FastAPI-MCP (SSE) → API ❌ SSE streaming issues ``` ### After (Working): ``` Claude Desktop → mcp_stdio_server.py → FastAPI API → Hostaway ✅ Native MCP stdio ✅ REST calls ``` ## What Was Fixed 1. **Created Native MCP Server** (`mcp_stdio_server.py`) - Implements MCP stdio protocol correctly - Defines 7 tools matching the API endpoints - Makes HTTP calls to localhost:8000 - Proper error handling and JSON formatting 2. **Added MCP SDK Dependency** ```bash uv add mcp # Added to pyproject.toml ``` 3. **Updated Claude Desktop Config** - Changed from HTTP/SSE approach to stdio server - Fixed PATH issue: Use full path `/Users/darrenmorgan/.local/bin/uv` - Command: `/Users/darrenmorgan/.local/bin/uv run python mcp_stdio_server.py` 4. **Verified MCP Server Works** ```bash echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize"}' | uv run python mcp_stdio_server.py # ✅ Returns JSON-RPC response ``` ## Current Status ### ✅ Fixed Components - Docker container: **Running and healthy** - FastAPI REST API: **Responding on localhost:8000** - MCP stdio server: **Responding to JSON-RPC requests** - Claude Desktop config: **Updated with correct command** ### 🧪 Ready to Test **Next Steps:** 1. **Restart Claude Desktop** (Cmd+Q, then reopen) 2. **Check MCP Servers tab** - "hostaway-mcp" should show as connected 3. **Verify 7 tools are available**: - `list_properties` - `get_property_details` - `check_availability` - `search_bookings` - `get_booking_details` - `get_guest_info` - `get_financial_reports` ## Testing Commands ### Verify Docker is Running ```bash docker compose ps # Should show: hostaway-mcp-server Up XX minutes (healthy) ``` ### Test API Directly ```bash curl http://localhost:8000/health # Should return: {"status": "healthy", ...} curl 'http://localhost:8000/api/listings?limit=2' | jq . # Should return: {"listings": [...], ...} ``` ### Test MCP Server ```bash cd /Users/darrenmorgan/AI_Projects/hostaway-mcp echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}}' | uv run python mcp_stdio_server.py # Should return JSON-RPC response ``` ### Claude Desktop Test In Claude Desktop, ask: ``` "Use hostaway-mcp to list my first 3 properties" ``` Expected behavior: - Claude invokes `list_properties` tool - Returns property data from Hostaway API ## Debugging Guide ### If Connection Still Fails 1. **Check Claude Desktop Logs**: ```bash # macOS location tail -f ~/Library/Logs/Claude/mcp*.log ``` 2. **Verify Environment**: ```bash uv --version # Should be installed python --version # Should be 3.12+ ``` 3. **Test MCP Server Manually**: ```bash uv run python mcp_stdio_server.py # Paste this and press Enter: {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}} ``` 4. **Check Docker Health**: ```bash docker compose logs --tail 50 hostaway-mcp ``` ### Common Issues | Issue | Fix | |-------|-----| | "Server disconnected" | Restart Claude Desktop completely (Cmd+Q) | | "Tools not loading" | Check Docker is running: `docker compose ps` | | "HTTP connection refused" | Ensure API is on port 8000: `curl http://localhost:8000/health` | | "Python module not found" | Reinstall: `uv sync` in project directory | ## Files Modified 1. ✅ Created: `mcp_stdio_server.py` - Native MCP server 2. ✅ Updated: `pyproject.toml` - Added `mcp>=1.17.0` dependency 3. ✅ Updated: `~/Library/Application Support/Claude/claude_desktop_config.json` 4. ✅ Updated: `CLAUDE_DESKTOP_SETUP.md` - Revised documentation ## Files Deprecated - ❌ `mcp_stdio_bridge.py` - Old HTTP/SSE bridge (no longer used) ## Success Criteria When working correctly, you should see: 1. ✅ Claude Desktop shows "hostaway-mcp" as **connected** (green status) 2. ✅ 7 tools visible in the MCP tools list 3. ✅ Can ask Claude to use Hostaway tools 4. ✅ Tools return real data from your Hostaway account 5. ✅ Structured logging in Docker container shows API requests ## Next Actions **Immediate:** 1. Restart Claude Desktop (Cmd+Q) 2. Verify connection in MCP servers tab 3. Test with: "List my Hostaway properties" **If Working:** 4. Test all 7 tools 5. Verify rate limiting (15 req/10s) 6. Check OAuth token refresh **If Still Failing:** - Share Claude Desktop logs from `~/Library/Logs/Claude/` - Check MCP server output: Run manually and share errors - Verify Docker logs: `docker compose logs hostaway-mcp` --- **Status**: ✅ **FIXED - Ready for Testing** The MCP server is now properly implemented using the native stdio protocol. Simply restart Claude Desktop to connect!