PointsYeah MCP Middleware Server

A secure, multi-tenant Model Context Protocol (MCP) middleware server designed to be hosted on Google Cloud Run. It exposes the complete PointsYeah Public API to AI agents (such as Claude Desktop, Cursor, and custom agentic systems) while strictly following web best practices for security, authorization, and rate limiting.

🌟 Key Architecture & Highlights

flowchart LR
    subgraph Clients["MCP Clients"]
        A["Claude Desktop / Cursor\n(Owner)"]
        B["Team / External User\n(With Own API Key)"]
    end

    subgraph GCP["Google Cloud Run (Serverless)"]
        M1["Security & Headers Middleware"]
        M2["Rate Limiting (60 req/min)"]
        M3["Server Token Auth Gate\n(Bearer / X-Server-API-Key)"]
        APP["PointsYeah MCP Server\n(SSE: /sse, /messages)"]
        Tools["10 Tools (Flights & Hotels)"]
    end

    subgraph Upstream["PointsYeah API"]
        PY["https://ai-api.pointsyeah.com\n(40+ Airline & Hotel Programs)"]
    end

    A -->|Auth: Bearer ServerToken| M1
    B -->|Auth: Bearer ServerToken\nX-PointsYeah-API-Key: UserKey| M1
    M1 --> M2 --> M3 --> APP --> Tools
    Tools -->|Resolves Key & Forwards| PY

1. Multi-Tenancy & Credential Management

• Zero Quota Leakage: PointsYeah enforces a daily quota (1,000 calls/day on premium). Other users can provide their own PointsYeah credentials, consuming their quota instead of yours.

• Three Flexible Ways to Provide Upstream Keys:

  1. Client HTTP Header: X-PointsYeah-API-Key: <key> in MCP client configuration.

  2. Tool Argument: pointsyeah_api_key: "<key>" directly in tool calls or prompts.

  3. Server Default: DEFAULT_POINTSYEAH_API_KEY configured in Cloud Run for seamless single-user access by the server owner.

2. Security & Access Control

• Authentication Gate: Only authorized clients with a valid server token can access the MCP endpoints. Requests without authorization are rejected with HTTP 401 Unauthorized.

• Flexible Authentication Methods:

  • Authorization: Bearer <SERVER_API_KEY>

  • X-Server-API-Key: <SERVER_API_KEY>

  • Query Parameter: ?token=<SERVER_API_KEY> (for MCP clients without custom header support)

• Multi-User Token Attributions: Supports multiple named tokens (e.g. SERVER_API_KEYS=owner:token1,alice:token2) with timing-safe comparison (hmac.compare_digest).

• Abuse Prevention: Built-in sliding-window rate limiter (default: 60 requests/minute) prevents denial of service and runaway Cloud Run bills.

• Web Security Standards: Strict security headers (nosniff, DENY frames, HSTS, strict-origin), restricted CORS, non-root Docker user (appuser), and public /healthz endpoints for Cloud Run probes.

Related MCP server: PointsYeah MCP Server

🛠️ Available MCP Tools

✈️ Flights Suite

🏨 Hotels Suite

🚀 Quick Start (Local Development)

1. Setup Environment

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Configure Environment Variables

Copy .env.example to .env:

cp .env.example .env

Edit .env:

# Upstream PointsYeah Key (from https://www.pointsyeah.com/developers/getting-started)
DEFAULT_POINTSYEAH_API_KEY=your_pointsyeah_api_key

# Secret token required to connect to this server
SERVER_API_KEY=my_secure_server_token_12345

3. Run Test Suite

pytest -v

4. Start Local Server

python3 -m src.server

The server will start at http://localhost:8080:

• Health check: http://localhost:8080/healthz

• MCP SSE endpoint: http://localhost:8080/sse

☁️ Deploying to Google Cloud Run

Option 1: Automated Script (deploy.sh)

Ensure you have the gcloud CLI installed and authenticated (gcloud auth login). Then run:

./deploy.sh

The script will:

1. Verify Google Cloud SDK and project.

2. Enable Cloud Run and Cloud Build APIs.

3. Prompt for or generate a secure SERVER_API_KEY.

4. Deploy the container to Cloud Run with automatic scaling (0 to 5 instances).

5. Output the live Cloud Run URL and ready-to-copy client configuration blocks.

Option 2: Direct gcloud CLI

# 1. Enable services
gcloud services enable run.googleapis.com cloudbuild.googleapis.com

# 2. Deploy from source
gcloud run deploy pointsyeah-mcp \
  --source . \
  --region us-central1 \
  --platform managed \
  --allow-unauthenticated \
  --set-env-vars SERVER_API_KEY="your-secret-server-token" \
  --set-env-vars DEFAULT_POINTSYEAH_API_KEY="your-pointsyeah-key" \
  --memory 512Mi \
  --cpu 1 \
  --min-instances 0 \
  --max-instances 5 \
  --port 8080

Note on --allow-unauthenticated: Cloud Run's native IAM requires Google OAuth/OIDC tokens which standard desktop MCP clients do not support. Our application-level authentication middleware validates high-entropy Bearer tokens/API keys on every request.

💻 Client Configuration

Claude Desktop

Edit your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Server Owner Configuration:

{
  "mcpServers": {
    "pointsyeah": {
      "url": "https://pointsyeah-mcp-xxxxxx-uc.a.run.app/sse",
      "headers": {
        "Authorization": "Bearer your-secret-server-token"
      }
    }
  }
}

Shared User Configuration (Providing Their Own PointsYeah Key):

{
  "mcpServers": {
    "pointsyeah": {
      "url": "https://pointsyeah-mcp-xxxxxx-uc.a.run.app/sse",
      "headers": {
        "Authorization": "Bearer your-secret-server-token",
        "X-PointsYeah-API-Key": "USER_OWN_POINTSYEAH_API_KEY"
      }
    }
  }
}

Cursor IDE

Add to .cursor/mcp.json or Global Settings:

{
  "mcpServers": {
    "pointsyeah": {
      "url": "https://pointsyeah-mcp-xxxxxx-uc.a.run.app/sse",
      "headers": {
        "Authorization": "Bearer your-secret-server-token"
      }
    }
  }
}

Clients with URL-only Auth (e.g., query param)

If your MCP client does not support custom HTTP headers on SSE connections:

https://pointsyeah-mcp-xxxxxx-uc.a.run.app/sse?token=your-secret-server-token

🔒 Security Best Practices Checklist

• Timing-Safe Token Comparison: Protected against timing attacks via hmac.compare_digest.

• Zero Credential Leakage: PointsYeah API keys and server tokens are never echoed in logs or error messages.

• Least Privilege Container: Dockerfile executes as unprivileged user appuser (UID 10001).

• DDoS & Cost Protection: In-memory rate limiting and Cloud Run max-instance capping (--max-instances 5).

• Scale to Zero: Scales to 0 instances when not in use, incurring $0 base hosting costs.

• Public Health Probes: /healthz endpoint accessible by Cloud Run without exposing secrets.