Skip to main content
Four production-ready examples demonstrating MCP server patterns. Each example is fully runnable, deployable, and teaches key concepts beyond just authentication.

​
Comparison

ExampleWhat It DoesAuth PatternComplexityBest For
ISS TrackerReal-time space station locationNoneMinimalLearning MCP basics, public APIs
Weather APICurrent weather & forecastsAPI KeyLowSimple auth, proxying user credentials
WHOOP IntegrationHealth data (sleep, recovery)OAuth ProxyMediumWrapping existing OAuth APIs
Bookmark ManagerPersonal bookmark storageOAuth + DCRMediumBuilding new multi-user services

​
When to Use Each Pattern

​
No Authentication → ISS Tracker

  • Public APIs with no user-specific data
  • Testing and learning MCP
  • Read-only data sources
Start here if: You’re new to MCP or building with public APIs.

​
API Key → Weather API

  • Users provide their own API keys
  • Simple credential validation
  • No OAuth complexity needed
Start here if: You’re proxying to an API that uses keys (WeatherAPI, OpenAI, etc.)

​
OAuth Proxy → WHOOP Integration

  • Third-party service already has OAuth
  • You’re wrapping their existing API
  • Service doesn’t support Dynamic Client Registration
Start here if: You’re building integrations for GitHub, Strava, Spotify, or any OAuth API.

​
Remote OAuth + DCR → Bookmark Manager

  • Building a new service from scratch
  • Need MCP spec compliance
  • Want automatic client registration
Start here if: You’re creating a new multi-user service and want production-grade auth.

​
Repository Structure

All examples live in one repository: 
poke-mcp-examples/
├── iss-tracker/           # No auth
├── weather-api/           # API key
├── whoop-integration/     # OAuth Proxy
└── bookmark-manager/      # OAuth + DCR
Each directory contains:
  • src/server.py - MCP server implementation
  • requirements.txt - Python dependencies
  • .env.example - Environment template (if needed)
  • README.md - Detailed setup and deployment instructions

​
Getting Started Locally

Every example follows the same setup pattern: 
# 1. Clone the repository
git clone https://github.com/InteractionCo/poke-mcp-examples.git
cd poke-mcp-examples/<example-name>

# 2. Create conda environment
conda create -n <example-name> python=3.12
conda activate <example-name>

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure (if needed)
# Some examples need .env - see individual README
cp .env.example .env  # if exists
# Edit .env with your credentials

# 5. Run locally
python src/server.py
Your server will start on http://localhost:8000 (or the port specified in the example).

​
Local Testing with MCP Inspector

Before deploying, test your MCP server locally using the MCP Inspector: 
# Start your server
python src/server.py

# In another terminal, run the inspector
npx @modelcontextprotocol/inspector
The Inspector will automatically open in your browser. Connect to http://localhost:PORT/mcp (use the port your server is running on, usually 8000) and select “Via Proxy” as the connection type. You can then:
  • View all available tools and their schemas
  • Execute tools with test parameters
  • Inspect request/response payloads
  • Debug tool execution issues
OAuth examples may not work in MCP Inspector due to CORS restrictions. The Inspector runs in a browser, and OAuth redirect flows can conflict with browser security policies. For OAuth integrations, test directly by deploying to HTTPS and connecting through Poke or another client like Claude.

​
Deploying to Production

Poke requires HTTPS for production integrations. Local HTTP (http://localhost) works for testing, but deployed servers must use HTTPS.
All examples can be deployed to Render, which provides free HTTPS certificates.

​
Deployment Steps

1. Prepare Your Repository Fork or push the example to your own GitHub repository: 
# If you made changes locally, push to your fork
git remote add origin https://github.com/YOUR_USERNAME/poke-mcp-examples.git
git push -u origin main
2. Create Web Service on Render
  1. Sign up at render.com
  2. Click New + → Web Service
  3. Connect your GitHub account
  4. Select your repository
3. Configure Build Settings
  • Root Directory: Set to the example folder (e.g., iss-tracker, weather-api, etc.)
  • Build Command: pip install -r requirements.txt
  • Start Command: python src/server.py
  • Environment: Python 3
4. Set Environment Variables (if needed) Some examples require configuration:
ExampleRequired VariablesNotes
ISS TrackerNoneNo config needed
Weather APINoneAPI keys come from users
WHOOP IntegrationWHOOP_CLIENT_ID
WHOOP_CLIENT_SECRET
PUBLIC_BASE_URL		Create OAuth app in WHOOP dashboard first
Bookmark ManagerAUTHKIT_DOMAIN
PUBLIC_BASE_URL		Create WorkOS account, enable DCR
Add environment variables in Render dashboard under Environment. Set PUBLIC_BASE_URL to your Render URL: https://your-service.onrender.com 5. Deploy Click Create Web Service. Render will:
  • Build your Python environment
  • Install dependencies
  • Start your server
  • Assign an HTTPS URL
6. Get Your Server URL Your deployed server will be at: 
https://your-service-name.onrender.com/mcp
7. Connect to Poke
  1. Go to poke.com/settings/connections/integrations/new
  2. Enter your server URL (with /mcp path)
  3. Add API key or complete OAuth flow (if required)
  4. Test your integration

​
Deployment Notes

Free Tier Limitations Render’s free tier spins down after 15 minutes of inactivity. First request after sleep takes ~30 seconds to wake up. Visit your URL in a browser to wake it before connecting to Poke. Updating Your Integration
  • Push changes to GitHub (Render auto-deploys if enabled)
  • Or manually deploy from Render dashboard
  • Important: After code changes, disconnect and reconnect in Poke to refresh tool schemas
Troubleshooting
  • View logs in Render dashboard under Logs tab
  • Most common issues: missing environment variables, incorrect paths, cold starts
  • For OAuth examples: ensure redirect URIs match your PUBLIC_BASE_URL
Custom Domains Render supports custom domains on paid plans. Update PUBLIC_BASE_URL environment variable and reconnect in Poke. For example-specific deployment details (OAuth setup, database configuration, etc.), see individual README files in the repository.

​
What You’ll Learn

Each example demonstrates multiple concepts beyond just authentication: Authentication Patterns
  • ISS Tracker: No authentication (baseline pattern)
  • Weather API: API key validation against upstream services
  • WHOOP: OAuth Proxy for third-party APIs
  • Bookmark Manager: Remote OAuth + DCR for new services
Tool Design
  • ISS Tracker: Human-readable responses optimized for conversational AI
  • Weather API: Flexible parameters in single tools
  • WHOOP: Combining API calls to minimize latency (detailed in Tool Design Philosophy)
  • Bookmark Manager: Per-user data isolation
Production Patterns
  • Rate limiting (per-key, per-user)
  • Token validation and caching
  • Error handling and graceful degradation
  • HTTPS deployment and security

​
Getting Help

Issues with examples? Open an issue on GitHub Questions about authentication? See Authentication Concepts for detailed explanations of each pattern. Need more complex examples? WHOOP demonstrates advanced patterns like tool design and latency optimization. Check Tool Design Philosophy for deep dive.