Poke MCP Production Server

You are equipped with a production-ready Pokémon MCP server that provides a fast HTTP API for MCP tools, secure authentication, health checks, metrics, and structured logs. It is designed to serve MCP clients that need to fetch Pokémon data, run battle simulations, and monitor usage in a scalable, secure way.

How to use

You connect to the MCP server using an API key and make requests to protected endpoints to execute MCP tools. Start by ensuring your API key is configured in your environment, then call the available MCP tool endpoints to fetch Pokémon information or run battles. Monitor responses through status endpoints and logs to verify correct behavior. Ensure metrics collection is enabled to observe request counts, latency, and tool invocations.

How to install

Prerequisites: Python 3.11+, either uv (recommended) or pip, and a Vercel account for deployment.

Step by step install and run locally in stdio mode (local testing):

# Start the local stdio server
python server.py

How to run in HTTP mode (production)

Start the HTTP server to accept requests remotely from MCP clients. This uses an HTTP transport with a FastMCP server instance.

uvicorn api.index:app --reload --host 0.0.0.0 --port 8000

Test the server

Health check and protected endpoint tests confirm proper operation. Use a health GET request and a protected status request with your API key.

# Health check
curl http://localhost:8000/health

# Protected endpoint (requires API key)
curl -H "Authorization: Bearer YOUR_API_KEY" http://localhost:8000/status

Configuration and security considerations

All configuration is controlled via environment variables. The following options are commonly used to tune behavior and security.

# Environment variables (examples)
API_KEY=REPLACE_WITH_STRONG_KEY
ALLOWED_ORIGINS=http://localhost:*.localhost
LOG_LEVEL=INFO
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60
ENABLE_METRICS=true

Monitoring and logging

Prometheus metrics are exposed at the /metrics endpoint when enabled. You will see metrics for HTTP requests, tool calls, durations, and active connections. Logs are emitted in structured JSON format with request tracing and tool execution details.

Notes on security

Protect the API with strong API keys, restrict origins via ALLOWED_ORIGINS, enable rate limiting, use HTTPS in production, and avoid committing secrets in code. SSH tunneling is supported for secure remote access.

Troubleshooting

If the server won’t start, verify you are using Python 3.11+ and that dependencies are installed. Check your environment variables and ensure the API key is set correctly. For authentication failures, confirm the Authorization header uses the Bearer scheme and that the API key matches the configured value.

Tools and endpoints

You have access to two MCP tools: get_pokemon_info and simulate_battle. Use these endpoints to retrieve comprehensive Pokémon details, including stats, types, abilities, and evolution chains, or to run a structured battle simulation with a detailed battle log.

Available tools

get_pokemon_info

Fetches detailed Pokémon information including base stats, types, abilities, moves (first 10), and full evolution chain.

simulate_battle

Runs a turn-based Pokémon battle simulation with type effectiveness, status effects, and a detailed battle log.