Enhanced POE MCP Server for Warp.dev

A production-ready Model Context Protocol (MCP) server that integrates POE (Poe.com API) with Warp.dev terminal, enabling AI-powered terminal assistance with context-aware tooling, automated workflows, and real-time streaming capabilities.

🚀 Features

Core Capabilities

• Multi-Model Support: Access GPT-4o, Claude 3 Opus/Sonnet, Gemini Pro, Perplexity, and O3 models

• Warp Terminal Integration: Deep integration with Warp's context extraction and action execution

• OpenAI SDK Compatibility: Drop-in replacement for OpenAI API with POE backend

• Production-Ready: Rate limiting, health checks, metrics, and graceful shutdown

Advanced Features

• Context-Aware Queries: Automatically extracts terminal output, selections, CWD, git state

• Real-Time Streaming: Server-Sent Events (SSE) with delta content streaming

• Command Execution: Safe execution of terminal commands with validation

• File Operations: Create and modify files directly from model responses

• Session Management: Maintain conversation context across multiple queries

• Rate Limiting: Exponential backoff with 500 RPM limit and request queuing

• Health Monitoring: Built-in health checks and Prometheus-style metrics

Related MCP server: MCP Server for Replicate

📋 Prerequisites

• Operating System: Linux (tested on Ubuntu, Zorin OS), macOS, or WSL2 on Windows

• Python: Version 3.8 or higher

• Warp Terminal: Download from warp.dev

• POE API Key: Get yours from poe.com/api_key

🔧 Installation

Step 1: Clone and Setup

Step 2: Configure Environment

Create a .env file with your credentials:

Step 3: Configure in Warp Terminal

Option A: Local Installation (Can cause stability issues)

1. Open Warp MCP Settings:

   • Navigate to: Settings → AI → Manage MCP servers

   • Or press Ctrl+P (Linux/Windows) or Cmd+P (macOS) and search for "Open MCP Servers"

2. Add the POE MCP Server: Click the + Add button and paste this configuration:

   { "enhanced-poe-mcp": { "command": "python3", "args": ["/home/david/Projects/Kijko/MVP/MVP_Kijko/enhanced-poe-mcp/poe_server_phase2.py"], "env": { "POE_API_KEY": "your_poe_api_key_here", "PYTHONUNBUFFERED": "1", "DEBUG_MODE": "false", "RATE_LIMIT_RPM": "500" } } }

   Important: Replace /home/david/Projects/Kijko/MVP/MVP_Kijko/enhanced-poe-mcp with your actual installation path.

3. Save and Start:

   • Click Save to add the configuration

   • Click Start next to your server entry

   • The server status should show as "Running"

Option B: Remote Hosting (Recommended for Stability)

Warp supports remote MCP servers! Host your MCP server remotely to avoid local stability issues.

1. Deploy to Railway.app (Best free option):

   # Prepare for deployment cd enhanced-poe-mcp echo "web: python poe_server_phase2.py" > Procfile git add . git commit -m "Add Procfile for Railway" git push origin main

2. Configure Railway:

   • Sign up at railway.app

   • Create new project → Deploy from GitHub

   • Add environment variables in Railway dashboard:

     • POE_API_KEY

     • PORT=8000

     • Any other config variables

3. Configure Warp for Remote MCP:

   { "enhanced-poe-mcp": { "url": "https://your-app.up.railway.app/mcp/stream" } }

Alternative Hosting Options:

• Render.com: Good free tier, easy deployment

• Google Cloud Run: Generous free tier, requires Docker

• Fly.io: Global deployment, more complex setup

• Vercel: ❌ NOT COMPATIBLE - Cannot handle persistent connections, SSE streaming, or long-running tasks

🎮 Usage in Warp Terminal

Specifying POE Models

POE is a marketplace with hundreds of LLMs. You must specify which model to use:

Popular Model Identifiers:

Basic POE Query

Query with File Attachment

Context-Aware Query

Execute Terminal Commands

Stream Long Responses

Session Management

List Available Models

Health Check

🛠️ Advanced Configuration

Server Variants

The project includes multiple server implementations for different use cases:

Running Different Modes

Environment Variables Reference

📊 Monitoring & Metrics

Health Check Endpoint

Metrics Endpoint

🐛 Troubleshooting

MCP Server Won't Start in Warp

Issue: Server fails to start or shows as "Error" in Warp MCP panel

Solutions:

1. Verify Python path: which python3 and update configuration

2. Check file permissions: chmod +x poe_server_phase2.py

3. Test manually: cd /path/to/server && python3 poe_server_phase2.py

4. Check logs: Look for errors in terminal output

Authentication Errors

Issue: "Invalid API key" or "Authentication failed"

Solutions:

1. Verify POE_API_KEY in .env file

2. Ensure key is added to Warp MCP config environment

3. Test key at poe.com/api_key

Rate Limiting Issues

Issue: "Rate limit exceeded" errors

Solutions:

1. Increase RATE_LIMIT_RPM in configuration

2. Enable request queuing (automatic in Phase 2 server)

3. Implement exponential backoff in client code

Context Not Working

Issue: POE doesn't see terminal output or context

Solutions:

1. Use poe_server_phase2.py (not basic server)

2. Ensure Warp context permissions are enabled

3. Update to latest Warp version

Linux-Specific Issues

Issue: Permission denied or module not found

Solutions:

🚀 Remote Deployment Guide (Railway)

Why Host Remotely?

• Avoids local stability issues

• Always available, even when your machine is off

• Centralized configuration management

• Better for team collaboration

Step-by-Step Railway Deployment

1. Prepare Your Project:

   cd enhanced-poe-mcp # Create Procfile for Railway echo 'web: python poe_server_phase2.py' > Procfile # Ensure requirements.txt is complete pip freeze > requirements.txt # Create runtime.txt for Python version echo "python-3.11.x" > runtime.txt # Commit changes git add . git commit -m "Add Railway deployment files" git push origin main

2. Set Up Railway:

   • Sign up at railway.app (free with GitHub)

   • Click "New Project" → "Deploy from GitHub repo"

   • Select your enhanced-poe-mcp repository

   • Railway will auto-detect Python and begin deployment

3. Configure Environment Variables: In Railway dashboard, go to Variables tab and add:

   POE_API_KEY=your_poe_api_key_here PORT=8000 DEBUG_MODE=false RATE_LIMIT_RPM=500 PYTHONUNBUFFERED=1

4. Get Your Server URL:

   • Go to Settings tab in Railway

   • Under Domains, click "Generate Domain"

   • Copy your URL (e.g., https://your-app.up.railway.app)

5. Configure Warp with Remote URL:

   { "enhanced-poe-mcp": { "url": "https://your-app.up.railway.app/mcp/stream" } }

6. Test the Connection:

   # Test your remote server curl https://your-app.up.railway.app/health # Should return: # {"status": "healthy", "version": "2.0.0"}

Monitoring Your Remote Server

• Logs: View in Railway dashboard under "Deployments"

• Metrics: Check /metrics endpoint

• Health: Monitor /health endpoint

• Usage: Railway shows resource consumption in dashboard

🌗️ Architecture

🧪 Testing

📚 API Documentation

MCP Tools Reference

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Poe.com for the API access

• Warp.dev for the amazing terminal

• FastMCP for the MCP framework

• The open-source community for continuous support

📞 Support

• Issues: GitHub Issues

• Discussions: GitHub Discussions

• Documentation: Wiki

Note: This project is not affiliated with Poe.com or Warp.dev. It's an independent integration tool.