Google Cloud MCP Server

# Google Cloud MCP HTTP Server HTTP-based version of the Google Cloud MCP server supporting Server-Sent Events (SSE) transport for web-based access and real-time streaming. ## Overview This HTTP server implementation provides: - **Web-based access**: Connect from browsers and web applications - **Remote connections**: Access the MCP server over HTTP instead of stdio - **Concurrent sessions**: Multiple clients can connect simultaneously - **Real-time streaming**: Uses Server-Sent Events (SSE) for real-time communication - **RESTful endpoints**: Standard HTTP endpoints for health checks and capabilities ## Architecture The server uses: - **Express.js** for HTTP handling - **Server-Sent Events (SSE)** for real-time client communication - **JSON-RPC 2.0** for MCP protocol messages - **Session management** for multiple concurrent clients ## Setup ### 1. Install Dependencies ```bash pnpm add express cors @types/express @types/cors ``` ### 2. Build the Project ```bash npm run build ``` ### 3. Start the Server ```bash npm run start:http ``` The server will start on port **3001** by default (configurable via `PORT` environment variable). ## Endpoints ### `/mcp` - MCP Protocol Endpoint - **GET**: Establishes SSE connection for real-time communication - **POST**: Send JSON-RPC messages to the MCP server ### `/health` - Health Check ```bash curl http://localhost:3001/health ``` ### `/capabilities` - Server Capabilities ```bash curl http://localhost:3001/capabilities ``` ## Client Implementation ### Web Browser Example See `examples/http-client.html` for a complete web client implementation. Key features: - Establishes SSE connection - Sends JSON-RPC messages via POST - Handles session management - Real-time message logging ### JavaScript/Node.js Example ```javascript const eventSource = new EventSource('http://localhost:3001/mcp'); eventSource.onopen = () => { console.log('Connected to MCP server'); }; eventSource.onmessage = (event) => { const data = JSON.parse(event.data); console.log('Received:', data); }; // Send messages via POST async function sendMessage(message) { const response = await fetch('http://localhost:3001/mcp', { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-mcp-session-id': sessionId }, body: JSON.stringify(message) }); return response.json(); } ``` ## Configuration ### Environment Variables - `PORT`: Server port (default: 3001) - `GOOGLE_APPLICATION_CREDENTIALS`: Path to Google Cloud service account key - `GOOGLE_CLOUD_PROJECT`: Google Cloud project ID ### CORS Settings The server enables CORS for all origins by default. Modify `src/http-server.ts` for production security. ## Security Considerations ⚠️ **Important for Production:** - Implement authentication (API keys, OAuth, etc.) - Configure CORS for specific domains only - Add rate limiting - Use HTTPS in production - Validate and sanitize all inputs ## Monitoring The server provides: - Health check endpoint (`/health`) - Request logging middleware - Session connection tracking - Error handling and logging ## Differences from Stdio Version | Feature | Stdio | HTTP | |---------|-------|------| | Access | Local process only | Remote HTTP access | | Clients | Single client | Multiple concurrent clients | | Protocol | stdin/stdout | HTTP + SSE | | Web support | No | Yes | | Session management | Not needed | Required | ## Troubleshooting ### Common Issues 1. **CORS Errors** - Check browser console for CORS messages - Verify server CORS configuration 2. **Connection Refused** - Ensure server is running on correct port - Check for port conflicts (use `lsof -i :3001`) 3. **Session Management** - Verify `x-mcp-session-id` header is included in POST requests - Check SSE connection is established before sending messages ### Debugging Enable debug logging: ```bash DEBUG=* npm run start:http ``` ## Performance - **Memory Usage**: Higher than stdio due to session management - **Latency**: Minimal overhead from HTTP layer - **Throughput**: Supports multiple concurrent connections - **Scalability**: Can be load balanced behind reverse proxy ## Migration from Stdio 1. Update client code to use HTTP endpoints instead of stdio 2. Implement session management in client 3. Handle SSE events for real-time communication 4. Update error handling for HTTP responses 5. Consider authentication and security requirements --- **Note**: This HTTP implementation is designed for development and testing. For production use, implement proper authentication, authorization, and security measures.