---
title: Phoenix MCP API Integration Guide
version: 1.1
last_updated: 2026-04-26
audience: External integrators, AI agents, automation systems
---

# Phoenix MCP API Integration Guide

This guide provides complete specifications for integrating with Phoenix CVE Intelligence via the Model Context Protocol (MCP) JSON-RPC API. It covers both **Normal API** (customer-facing) and **PAPI** (Privileged API for Phoenix Global Admins).

## Table of Contents

- [Overview](#overview)
- [API Planes](#api-planes)
- [Authentication](#authentication)
- [Endpoint Structure](#endpoint-structure)
- [Request/Response Format](#requestresponse-format)
- [Available Methods](#available-methods)
- [Resources](#resources)
- [Tools](#tools)
- [Tiered Access Control](#tiered-access-control)
- [Examples](#examples)
- [Error Handling](#error-handling)
- [Rate Limits](#rate-limits)
- [Integration Patterns](#integration-patterns)

---

## Overview

Phoenix MCP API provides:

- **CVE Intelligence**: Enriched CVE data with Phoenix proprietary scoring (PS-HP, PS-EW)
- **EOL Intelligence**: End-of-life product tracking and CVE correlation
- **Threat Intelligence**: Threat actor mappings, KEV catalog, enterprise watchlist
- **Scoring Services**: Phoenix scoring algorithms with component breakdown
- **JSON-RPC 2.0**: Standard protocol for LLM integrations (Claude, ChatGPT, custom agents)

**Protocol**: JSON-RPC 2.0 (MCP specification)  
**Transport**: HTTP POST  
**Content-Type**: `application/json`

---

## API Planes

Phoenix exposes two API planes with different access levels:

| Plane | Path Prefix | Audience | Auth Method | Data Access |
|-------|-------------|----------|-------------|-------------|
| **Normal API** | `/api/v1/mcp` | Customers, external agents | API Key (x-api-key) | Tier-filtered responses |
| **PAPI** (Privileged) | `/internal/v1/mcp` | Phoenix Global Admins | PAI Key (x-pai-key) + IP allowlist | Full unredacted data |

### Normal API

- **Endpoint**: `POST /api/v1/mcp`
- **Aliases**: 
  - `POST /api/v1/mcp/claude` (Claude Desktop connector)
  - `POST /api/v1/mcp/chatgpt` (ChatGPT Desktop connector)
- **Access**: Public (with API key — Pro / Enterprise tiers). Generate one self-service under **My Account → Platform API Keys → MCP Client**. Full walkthrough: [Platform API Keys](PLATFORM_API_KEYS.md).
- **Response Filtering**: Tier-based (Registered/Pro/Enterprise)

### PAPI (Privileged API)

- **Endpoint**: `POST /internal/v1/mcp`
- **Access**: Restricted to Phoenix Global Admins
- **Response Filtering**: None (full data access)
- **Additional Security**: IP allowlist + PAI key validation

---

## Authentication

### Normal API Authentication

**Header**: `x-api-key: <your_api_key>`

**Allowed Scopes**:
- `mcp` - Basic MCP access (Registered tier)
- `api_power` - Enhanced access (Pro tier)
- `api_integration` - Integration access (Pro tier)
- `api_unlimited` - Full access (Enterprise tier)

**Example**:
```bash
curl -X POST https://phoenix.example.com/api/v1/mcp \
  -H "Content-Type: application/json" \
  -H "x-api-key: phx_api_power_abc123..." \
  -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{}}'
```

### PAPI Authentication

**Headers**:
- `x-pai-key: <your_pai_key>` (or `x-api-key`)
- Source IP must be in `PAI_IP_ALLOWLIST`

**Example**:
```bash
curl -X POST https://phoenix-internal.example.com/internal/v1/mcp \
  -H "Content-Type: application/json" \
  -H "x-pai-key: pai_admin_xyz789..." \
  -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{}}'
```

**PAI Key Generation**:
1. Request key: `POST /api/v1/admin/pai/request-key` (Global Admin only)
2. Verify email token: `POST /api/v1/admin/pai/verify-and-generate`
3. Use generated PAI key (shown once, store securely)

---

## Endpoint Structure

### Base URLs

| Environment | Normal API | PAPI |
|-------------|-----------|------|
| Production | `https://api.phoenix.example.com/api/v1/mcp` | `https://internal.phoenix.example.com/internal/v1/mcp` |
| Staging | `https://staging-api.phoenix.example.com/api/v1/mcp` | `https://staging-internal.phoenix.example.com/internal/v1/mcp` |
| Local Dev | `http://localhost:8000/api/v1/mcp` | `http://localhost:8000/internal/v1/mcp` |

---

## Request/Response Format

### JSON-RPC 2.0 Structure

**Request**:
```json
{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "method_name",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}
```

**Success Response**:
```json
{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": {
    "data": "..."
  }
}
```

**Error Response**:
```json
{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "error": {
    "code": -32000,
    "message": "Error description",
    "data": {
      "details": "Additional context"
    }
  }
}
```

### Standard Error Codes

| Code | Meaning |
|------|---------|
| `-32600` | Invalid Request (malformed JSON or missing required fields) |
| `-32601` | Method Not Found |
| `-32602` | Invalid Params |
| `-32000` | Server Error (generic) |
| `-32001` | Permission Denied (tier restriction) |

---

## Available Methods

### Core Methods

| Method | Description | Auth Required |
|--------|-------------|---------------|
| `initialize` | Get server info and capabilities | Yes |
| `resources/list` | List available read-only resources | Yes |
| `resources/read` | Fetch resource data by URI | Yes |
| `tools/list` | List available tools and input schemas | Yes |
| `tools/call` | Execute a tool with arguments | Yes |

---

## Resources

Resources are read-only data endpoints accessed via `resources/read` method.

### Resource URIs

| URI Pattern | Description | Example |
|-------------|-------------|---------|
| `phoenix://cve/{cve_id}` | CVE intelligence with PS-HP scoring | `phoenix://cve/CVE-2024-27198` |
| `phoenix://kev/catalog` | CISA Known Exploited Vulnerabilities | `phoenix://kev/catalog` |
| `phoenix://threat-actors` | Threat actor to CVE mappings | `phoenix://threat-actors` |
| `phoenix://high-profile/tier/{tier}` | High-profile CVEs by tier (1-3) | `phoenix://high-profile/tier/1` |
| `phoenix://enterprise-watchlist` | Enterprise watchlist (PS-EW) | `phoenix://enterprise-watchlist` |
| `phoenix://enterprise-cpe/{category}` | Enterprise CPE registry | `phoenix://enterprise-cpe/all` |
| `phoenix://eol/products` | EOL product catalog | `phoenix://eol/products` |
| `phoenix://eol/products/{slug}` | EOL product detail | `phoenix://eol/products/ubuntu` |
| `phoenix://eol/cve-correlation` | CVE/EOL correlation data | `phoenix://eol/cve-correlation` |
| `phoenix://eol/replacements` | EOL replacement recommendations | `phoenix://eol/replacements` |
| `phoenix://eol/statistics` | EOL summary statistics | `phoenix://eol/statistics` |
| `phoenix://eol/timeline` | Upcoming EOL events | `phoenix://eol/timeline` |

### Example: Read CVE Resource

**Request**:
```json
{
  "jsonrpc": "2.0",
  "id": "res-1",
  "method": "resources/read",
  "params": {
    "uri": "phoenix://cve/CVE-2024-27198"
  }
}
```

**Response (Normal API - Registered Tier)**:
```json
{
  "jsonrpc": "2.0",
  "id": "res-1",
  "result": {
    "contents": [
      {
        "uri": "phoenix://cve/CVE-2024-27198",
        "mimeType": "application/json",
        "text": "{\"cve\":{\"cve_id\":\"CVE-2024-27198\",\"description\":\"...\",\"cvss_score\":9.8,\"severity\":\"CRITICAL\"},\"phoenix_score\":{\"ps_hp_score\":8.7,\"ps_hp_tier\":1,\"ps_hp_tier_name\":\"Confirmed High-Profile\",\"hp_summary\":\"Critical vulnerability with active exploitation\",\"hp_reasons\":[\"In CISA KEV catalog\",\"CVSS 9.8 (Critical)\",\"Active exploitation detected\"],\"is_enterprise_watchlist\":false}}"
      }
    ]
  }
}
```

**Response (PAPI - Full Access)**:
```json
{
  "jsonrpc": "2.0",
  "id": "res-1",
  "result": {
    "contents": [
      {
        "uri": "phoenix://cve/CVE-2024-27198",
        "mimeType": "application/json",
        "text": "{\"cve\":{\"cve_id\":\"CVE-2024-27198\",\"description\":\"...\",\"cvss_score\":9.8,\"severity\":\"CRITICAL\"},\"phoenix_score\":{\"ps_hp_score\":8.7,\"ps_hp_tier\":1,\"ps_hp_tier_name\":\"Confirmed High-Profile\",\"components\":{\"cvss\":0.98,\"epss\":0.85,\"kev\":1.0,\"ransomware\":0.0,\"exploit\":0.92,\"enterprise\":0.88,\"github\":0.65,\"bugbounty\":0.0},\"hp_summary\":\"Critical vulnerability with active exploitation\",\"hp_reasons\":[\"In CISA KEV catalog\",\"CVSS 9.8 (Critical)\",\"Active exploitation detected\",\"Enterprise-critical vendor (JetBrains)\",\"High EPSS score (85th percentile)\"],\"hp_rationale\":\"This CVE scores 8.7/10 due to confirmed exploitation (KEV), critical CVSS, and enterprise impact. The vulnerability affects JetBrains TeamCity, a widely-used CI/CD platform in enterprise environments. Exploitation is trivial and has been observed in the wild.\",\"executive_summary\":\"Immediate patching required for all JetBrains TeamCity instances. Active exploitation confirmed by CISA.\",\"is_enterprise_watchlist\":false,\"enterprise_category\":\"DevOps Tools\",\"enterprise_risk_score\":9.2}}"
      }
    ]
  }
}
```

---

## Tools

Tools are executable functions accessed via `tools/call` method.

### Standard Tools (All Tiers)

| Tool Name | Description | Input Schema |
|-----------|-------------|--------------|
| `search_cves` | Search CVEs with filters | `{query?, year?, severity?, kev_only?, ps_hp_min?, ps_hp_tier?, enterprise_watchlist?, limit?, offset?}` |
| `get_cve_intelligence` | Get comprehensive CVE intelligence | `{cve_id: string}` (required) |
| `get_phoenix_score` | Calculate PS-HP score with breakdown | `{cve_id: string, include_rationale?: boolean}` |
| `get_high_profile_cves` | Get high-profile CVEs by tier | `{tier?: 1\|2\|3, limit?: number, enterprise_category?: string}` |
| `get_enterprise_watchlist` | Get PS-EW flagged CVEs | `{category?: string, limit?: number}` |
| `get_threat_actors_by_cve` | Get threat actors for CVE | `{cve_id: string}` |
| `check_enterprise_critical` | Check if vendor/product is enterprise-critical | `{vendor: string, product: string}` |
| `list_eol_products` | List EOL products | `{status?, category?, vendor?, search?, limit?, offset?}` |
| `get_eol_product` | Get EOL product detail | `{product_slug: string}` |
| `get_eol_cve_correlations` | Get CVE/EOL correlations | `{non_fixable_only?, kev_only?, min_cvss?, limit?, offset?}` |
| `get_cve_eol_status` | Get EOL status for CVE | `{cve_id: string}` |
| `get_eol_replacements` | List EOL replacement recommendations | `{category?, limit?}` |
| `get_eol_replacement` | Get replacement for product | `{product_slug: string}` |
| `get_eol_statistics` | Get EOL summary statistics | `{}` |
| `get_eol_timeline` | Get upcoming EOL events | `{days?: number, category?: string}` |
| `get_eol_risk_score` | Calculate SLR risk score | `{product_slug: string}` |
| `get_ai_attributed_cves` | Returns CVEs discovered or co-reported by frontier AI models (Claude/GPT/Gemini/Llama/Grok) or AI-native security firms (AISLE) | `{provider?: string[], program?: string[], min_cvss?: number, since?: string, limit?: number}` |

### `get_ai_attributed_cves` — Frontier Model Attribution

> Added 2026-04-26 as part of PRD-FMA-001 (v1.0).
> Gated by feature flag `enable_frontier_model_cve_intel` (default `false`). When the flag is off the tool is **hidden from `tools/list`** and `tools/call` returns a "tool not found" error.

**Input schema**:

```json
{
  "name": "get_ai_attributed_cves",
  "description": "Returns CVEs discovered or co-reported by frontier AI models (Claude, GPT, Gemini, Llama, Grok) or AI-native security firms (AISLE). Filters by provider, program (Glasswing, QuiltWorks, MADBugs), and confidence.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "provider": {"type": "array", "items": {"enum": ["anthropic","openai","google","meta","xai","aisle"]}},
      "program":  {"type": "array", "items": {"enum": ["glasswing","quiltworks","madbugs"]}},
      "min_cvss": {"type": "number"},
      "since":    {"type": "string", "format": "date"},
      "limit":    {"type": "integer", "default": 50, "maximum": 200}
    }
  }
}
```

**Example call**:

```json
{
  "jsonrpc": "2.0",
  "id": "fma-1",
  "method": "tools/call",
  "params": {
    "name": "get_ai_attributed_cves",
    "arguments": {
      "provider": ["anthropic", "aisle"],
      "min_cvss": 9.0,
      "since": "2026-01-01",
      "limit": 20
    }
  }
}
```

**Tier-restricted fields**: same projection as the REST endpoint `GET /api/v1/ai-attributed-model-cves` — Free / Registered users see provider and basic CVE fields; Pro adds `confidence_tier`, `credit_text`, `collaboration_chain`; Enterprise adds the numeric `confidence_score`.

Cross-reference: REST endpoint and full field tier table in [PUBLIC_API.md](PUBLIC_API.md). Feature doc: [docs/Individual_Feature/frontier-model-attribution-intelligence.md](../Individual_Feature/frontier-model-attribution-intelligence.md).

### Enterprise-Only Tools (Normal API)

| Tool Name | Description | Input Schema |
|-----------|-------------|--------------|
| `calculate_custom_phoenix_score` | Calculate PS-HP from custom inputs | `{cvss: number, epss?, in_kev?, has_ransomware?, exploit_status?, vendor?, product?, github_stars?, github_forks?, bugbounty_reports?}` |
| `explain_score_components` | Get detailed PS-HP component explanation | `{cve_id: string}` |

**Note**: Enterprise-only tools return error code `-32001` (Permission Denied) for non-Enterprise tier users on Normal API. PAPI has access to all tools regardless of tier.

### Example: Call Tool (Normal API)

**Request**:
```json
{
  "jsonrpc": "2.0",
  "id": "tool-1",
  "method": "tools/call",
  "params": {
    "name": "get_cve_intelligence",
    "arguments": {
      "cve_id": "CVE-2024-27198"
    }
  }
}
```

**Response (Registered Tier)**:
```json
{
  "jsonrpc": "2.0",
  "id": "tool-1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# CVE-2024-27198 Intelligence\n\n**Severity**: CRITICAL (CVSS 9.8)\n**Phoenix Score**: 8.7/10 (Tier 1 - Confirmed High-Profile)\n\n## Summary\nCritical authentication bypass in JetBrains TeamCity...\n\n## Key Risk Factors\n- In CISA KEV catalog\n- CVSS 9.8 (Critical)\n- Active exploitation detected\n\n## Recommendation\nImmediate patching required."
      },
      {
        "type": "json",
        "json": {
          "cve": {
            "cve_id": "CVE-2024-27198",
            "description": "Authentication bypass vulnerability in JetBrains TeamCity...",
            "cvss_score": 9.8,
            "severity": "CRITICAL",
            "published_date": "2024-03-04",
            "kev": {
              "is_kev": true,
              "date_added": "2024-03-05",
              "due_date": "2024-03-26"
            },
            "epss": {
              "score": 0.85,
              "percentile": 0.95
            }
          },
          "phoenix_score": {
            "ps_hp_score": 8.7,
            "ps_hp_tier": 1,
            "ps_hp_tier_name": "Confirmed High-Profile",
            "hp_summary": "Critical vulnerability with active exploitation",
            "hp_reasons": [
              "In CISA KEV catalog",
              "CVSS 9.8 (Critical)",
              "Active exploitation detected"
            ],
            "is_enterprise_watchlist": false
          }
        }
      }
    ]
  }
}
```

### Example: Call Tool (PAPI)

**Request**:
```json
{
  "jsonrpc": "2.0",
  "id": "tool-2",
  "method": "tools/call",
  "params": {
    "name": "calculate_custom_phoenix_score",
    "arguments": {
      "cvss": 9.8,
      "epss": 0.85,
      "in_kev": true,
      "exploit_status": "weaponized",
      "vendor": "JetBrains",
      "product": "TeamCity",
      "github_stars": 250,
      "github_forks": 45
    }
  }
}
```

**Response (PAPI - Full Components)**:
```json
{
  "jsonrpc": "2.0",
  "id": "tool-2",
  "result": {
    "content": [
      {
        "type": "json",
        "json": {
          "ps_hp_score": 8.7,
          "ps_hp_tier": 1,
          "ps_hp_tier_name": "Confirmed High-Profile",
          "components": {
            "cvss": 0.98,
            "epss": 0.85,
            "kev": 1.0,
            "ransomware": 0.0,
            "exploit": 0.92,
            "enterprise": 0.88,
            "github": 0.65,
            "bugbounty": 0.0
          },
          "hp_summary": "Critical vulnerability with weaponized exploits",
          "hp_reasons": [
            "In CISA KEV catalog",
            "CVSS 9.8 (Critical)",
            "Weaponized exploit available",
            "Enterprise-critical vendor (JetBrains)",
            "High EPSS score (85th percentile)"
          ],
          "hp_rationale": "This hypothetical CVE scores 8.7/10 due to confirmed KEV status, critical CVSS, weaponized exploits, and enterprise impact. The combination of high technical severity and active exploitation makes this a top-priority vulnerability.",
          "executive_summary": "Immediate action required. Weaponized exploits available for enterprise-critical infrastructure.",
          "enterprise_category": "DevOps Tools",
          "enterprise_risk_score": 9.2
        }
      }
    ]
  }
}
```

---

## Tiered Access Control

### Normal API Tiers

| Tier | API Key Scope | Phoenix Score Fields | High-Profile Fields | Enterprise CPE Fields |
|------|---------------|----------------------|---------------------|----------------------|
| **Registered** | `mcp`, `api_basic` | Score, tier, summary, generic reasons (top 3), watchlist flag | CVE ID, severity, CVSS, technology, score, tier, summary, KEV, EPSS, watchlist, generic reasons | Vendor, product, category only |
| **Pro** | `api_power`, `api_integration` | All Registered + component levels (H/M/L), enterprise category, specific reasons (top 5), abbreviated rationale | All Registered + enterprise category, specific reasons (top 5), GitHub repo count | All Registered + KEV count, ransomware count |
| **Enterprise** | `api_unlimited` | All Pro + numeric component values (0.0-1.0), full rationale, executive summary, enterprise risk score | All Pro + full component breakdown, rationale, risk scores, detailed GitHub stats | All Pro + risk_weight values, CVE IDs, full risk scoring |

### PAPI Access

PAPI bypasses all tier restrictions and returns full unredacted data:

- **Phoenix Score**: All numeric component values (0.0-1.0), full rationale, executive summary, internal scoring weights
- **High-Profile CVEs**: Complete dataset with all fields
- **Enterprise CPE**: Full risk weights, CVE mappings, proprietary classifications
- **Scoring Calculations**: Access to all scoring endpoints with neutral defaults for missing inputs

---

## Examples

### Example 1: Initialize Connection (Normal API)

**Request**:
```json
{
  "jsonrpc": "2.0",
  "id": "init-1",
  "method": "initialize",
  "params": {}
}
```

**Response**:
```json
{
  "jsonrpc": "2.0",
  "id": "init-1",
  "result": {
    "protocolVersion": "0.1.0",
    "serverInfo": {
      "name": "phoenix-mcp",
      "version": "1.0.0"
    },
    "capabilities": {
      "resources": {},
      "tools": {},
      "prompts": {},
      "logging": {}
    }
  }
}
```

### Example 2: List Available Tools (Normal API - Enterprise Tier)

**Request**:
```json
{
  "jsonrpc": "2.0",
  "id": "list-1",
  "method": "tools/list",
  "params": {}
}
```

**Response**:
```json
{
  "jsonrpc": "2.0",
  "id": "list-1",
  "result": {
    "tools": [
      {
        "name": "search_cves",
        "description": "Search CVEs with filters including PS-HP scoring",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {"type": "string"},
            "year": {"type": "integer"},
            "severity": {"type": "string", "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW"]},
            "kev_only": {"type": "boolean"},
            "ps_hp_min": {"type": "number"},
            "ps_hp_tier": {"type": "integer"},
            "enterprise_watchlist": {"type": "boolean"},
            "limit": {"type": "integer"},
            "offset": {"type": "integer"}
          }
        }
      },
      {
        "name": "get_cve_intelligence",
        "description": "Get comprehensive CVE intelligence with PS-HP/PS-EW scoring",
        "inputSchema": {
          "type": "object",
          "properties": {
            "cve_id": {"type": "string", "pattern": "^CVE-\\d{4}-\\d{4,}$"}
          },
          "required": ["cve_id"]
        }
      },
      {
        "name": "calculate_custom_phoenix_score",
        "description": "Calculate PS-HP score from custom inputs (hypothetical analysis)",
        "inputSchema": {
          "type": "object",
          "properties": {
            "cvss": {"type": "number", "minimum": 0, "maximum": 10},
            "epss": {"type": "number", "minimum": 0, "maximum": 1},
            "in_kev": {"type": "boolean"},
            "exploit_status": {"type": "string", "enum": ["none", "poc", "verified", "weaponized", "in_ransomware"]}
          },
          "required": ["cvss"]
        }
      }
    ]
  }
}
```

### Example 3: Search High-Profile CVEs (Normal API - Pro Tier)

**Request**:
```json
{
  "jsonrpc": "2.0",
  "id": "search-1",
  "method": "tools/call",
  "params": {
    "name": "search_cves",
    "arguments": {
      "ps_hp_tier": 1,
      "severity": "CRITICAL",
      "limit": 10
    }
  }
}
```

**Response (Pro Tier)**:
```json
{
  "jsonrpc": "2.0",
  "id": "search-1",
  "result": {
    "content": [
      {
        "type": "json",
        "json": {
          "results": [
            {
              "cve_id": "CVE-2024-27198",
              "description": "Authentication bypass in JetBrains TeamCity",
              "cvss_score": 9.8,
              "severity": "CRITICAL",
              "ps_hp_score": 8.7,
              "ps_hp_tier": 1,
              "components": "H/H/H/L/H/H/M/L",
              "enterprise_category": "DevOps Tools",
              "hp_reasons": [
                "In CISA KEV catalog",
                "CVSS 9.8 (Critical)",
                "Active exploitation detected",
                "Enterprise-critical vendor",
                "High EPSS score"
              ]
            }
          ],
          "total": 1,
          "limit": 10,
          "offset": 0
        }
      }
    ]
  }
}
```

### Example 4: Get EOL Product Detail (PAPI)

**Request**:
```json
{
  "jsonrpc": "2.0",
  "id": "eol-1",
  "method": "tools/call",
  "params": {
    "name": "get_eol_product",
    "arguments": {
      "product_slug": "ubuntu-1804"
    }
  }
}
```

**Response (PAPI - Full Data)**:
```json
{
  "jsonrpc": "2.0",
  "id": "eol-1",
  "result": {
    "content": [
      {
        "type": "json",
        "json": {
          "product_slug": "ubuntu-1804",
          "product_name": "Ubuntu 18.04 LTS",
          "vendor": "Canonical",
          "category": "Operating Systems",
          "eol_date": "2023-05-31",
          "support_status": "eol",
          "days_until_eol": -639,
          "cve_count": 1247,
          "non_fixable_cve_count": 89,
          "kev_cve_count": 12,
          "risk_score": 8.9,
          "replacement_recommendations": [
            {
              "product_slug": "ubuntu-2204",
              "product_name": "Ubuntu 22.04 LTS",
              "eol_date": "2027-04-30",
              "migration_complexity": "medium"
            }
          ]
        }
      }
    ]
  }
}
```

### Example 5: Error Response (Permission Denied)

**Request (Registered Tier trying Enterprise-only tool)**:
```json
{
  "jsonrpc": "2.0",
  "id": "err-1",
  "method": "tools/call",
  "params": {
    "name": "calculate_custom_phoenix_score",
    "arguments": {
      "cvss": 9.8
    }
  }
}
```

**Response**:
```json
{
  "jsonrpc": "2.0",
  "id": "err-1",
  "error": {
    "code": -32000,
    "message": "Tool 'calculate_custom_phoenix_score' requires Enterprise tier"
  }
}
```

---

## Error Handling

### Common Error Scenarios

| Scenario | Error Code | Message | Resolution |
|----------|-----------|---------|------------|
| Invalid API key | HTTP 401 | "API key required" | Provide valid `x-api-key` header |
| Insufficient tier | `-32000` | "Tool requires Enterprise tier" | Upgrade API key scope or use PAPI |
| Invalid CVE ID | `-32602` | "Invalid CVE ID" | Use format `CVE-YYYY-NNNNN` |
| Resource not found | `-32000` | "CVE not found" | Verify CVE exists in database |
| Rate limit exceeded | HTTP 429 | "Rate limit exceeded" | Wait for rate limit window reset |
| Invalid JSON | `-32600` | "Invalid JSON payload" | Fix JSON syntax |
| Unknown method | `-32601` | "Method not found" | Check method name spelling |
| Missing required param | `-32602` | "Missing required param: cve_id" | Provide required parameters |

### Error Response Structure

```json
{
  "jsonrpc": "2.0",
  "id": "request-id",
  "error": {
    "code": -32602,
    "message": "Missing required param: cve_id",
    "data": {
      "details": "The 'cve_id' parameter is required for this tool"
    }
  }
}
```

---

## Rate Limits

### Normal API Rate Limits

| Tier | Requests/Hour | Requests/Minute |
|------|---------------|-----------------|
| Registered | 100 | 10 |
| Pro | 500 | 50 |
| Enterprise | 5000 | 500 |

### PAPI Rate Limits

| Limit Type | Default Value | Configurable |
|------------|---------------|--------------|
| Requests/Minute | 100 | Yes (`PAI_RATE_LIMIT_PER_MINUTE`) |
| Requests/Hour | 1000 | Yes (`PAI_RATE_LIMIT_PER_HOUR`) |

**Rate Limit Headers** (Normal API):
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709136000
```

---

## Integration Patterns

### Pattern 1: Claude Desktop Integration (stdio bridge)

**Setup**:
1. Install bridge script: `scripts/mcp_http_bridge.py`
2. Configure environment:
```bash
export MCP_HTTP_URL="https://api.phoenix.example.com/api/v1/mcp/claude"
export MCP_API_KEY="phx_api_power_abc123..."
```
3. Run bridge: `python scripts/mcp_http_bridge.py`
4. Configure Claude Desktop to use stdio bridge

**Claude Desktop Config** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "phoenix": {
      "command": "python",
      "args": ["/path/to/mcp_http_bridge.py"],
      "env": {
        "MCP_HTTP_URL": "https://api.phoenix.example.com/api/v1/mcp/claude",
        "MCP_API_KEY": "phx_api_power_abc123..."
      }
    }
  }
}
```

### Pattern 2: Direct HTTP Integration (Custom Agent)

**Python Example**:
```python
import requests

class PhoenixMCPClient:
    def __init__(self, base_url: str, api_key: str):
        self.base_url = base_url
        self.headers = {
            "Content-Type": "application/json",
            "x-api-key": api_key
        }
        self.request_id = 0
    
    def call_method(self, method: str, params: dict = None):
        self.request_id += 1
        payload = {
            "jsonrpc": "2.0",
            "id": str(self.request_id),
            "method": method,
            "params": params or {}
        }
        response = requests.post(self.base_url, json=payload, headers=self.headers)
        response.raise_for_status()
        return response.json()
    
    def get_cve_intelligence(self, cve_id: str):
        return self.call_method("tools/call", {
            "name": "get_cve_intelligence",
            "arguments": {"cve_id": cve_id}
        })

# Usage
client = PhoenixMCPClient(
    "https://api.phoenix.example.com/api/v1/mcp",
    "phx_api_power_abc123..."
)
result = client.get_cve_intelligence("CVE-2024-27198")
print(result["result"]["content"][1]["json"]["phoenix_score"])
```

### Pattern 3: PAPI Integration (Internal Service)

**Python Example**:
```python
import requests

class PhoenixPAPIClient:
    def __init__(self, base_url: str, pai_key: str):
        self.base_url = base_url
        self.headers = {
            "Content-Type": "application/json",
            "x-pai-key": pai_key
        }
        self.request_id = 0
    
    def call_tool(self, tool_name: str, arguments: dict):
        self.request_id += 1
        payload = {
            "jsonrpc": "2.0",
            "id": str(self.request_id),
            "method": "tools/call",
            "params": {
                "name": tool_name,
                "arguments": arguments
            }
        }
        response = requests.post(self.base_url, json=payload, headers=self.headers)
        response.raise_for_status()
        return response.json()
    
    def calculate_custom_score(self, cvss: float, **kwargs):
        arguments = {"cvss": cvss, **kwargs}
        return self.call_tool("calculate_custom_phoenix_score", arguments)

# Usage
papi_client = PhoenixPAPIClient(
    "https://internal.phoenix.example.com/internal/v1/mcp",
    "pai_admin_xyz789..."
)
score = papi_client.calculate_custom_score(
    cvss=9.8,
    epss=0.85,
    in_kev=True,
    exploit_status="weaponized",
    vendor="JetBrains",
    product="TeamCity"
)
print(score["result"]["content"][0]["json"]["components"])
```

### Pattern 4: Batch Processing (Multiple CVEs)

**Python Example**:
```python
import requests
from typing import List

class PhoenixBatchClient:
    def __init__(self, base_url: str, api_key: str):
        self.base_url = base_url
        self.headers = {
            "Content-Type": "application/json",
            "x-api-key": api_key
        }
    
    def batch_get_cve_intelligence(self, cve_ids: List[str]):
        results = []
        for cve_id in cve_ids:
            payload = {
                "jsonrpc": "2.0",
                "id": cve_id,
                "method": "tools/call",
                "params": {
                    "name": "get_cve_intelligence",
                    "arguments": {"cve_id": cve_id}
                }
            }
            response = requests.post(self.base_url, json=payload, headers=self.headers)
            if response.status_code == 200:
                results.append(response.json())
        return results

# Usage
batch_client = PhoenixBatchClient(
    "https://api.phoenix.example.com/api/v1/mcp",
    "phx_api_unlimited_xyz..."
)
cve_list = ["CVE-2024-27198", "CVE-2024-3400", "CVE-2024-21887"]
results = batch_client.batch_get_cve_intelligence(cve_list)
for result in results:
    cve_data = result["result"]["content"][1]["json"]
    print(f"{cve_data['cve']['cve_id']}: PS-HP {cve_data['phoenix_score']['ps_hp_score']}")
```

---

## Additional Resources

- **MCP Server Documentation**: `docs/MCP_SERVER.md`
- **PAI Documentation**: `docs/key_doc_and_architecture/PAI_INTERNAL_API.md`
- **API Keys Reference**: `docs/key_doc_and_architecture/API_KEYS_REFERENCE.md`
- **Tier Access Guide**: `docs/key_doc_and_architecture/USER TYPE and LEVELS - ACCESS_TIERS_AND_API.md`
- **Bridge Scripts**: `scripts/mcp_http_bridge.py`, `scripts/mcp_http_bridge_chatgpt.py`

---

## Support

For integration support, contact:
- **Email**: api-support@phoenix.example.com
- **Documentation**: https://docs.phoenix.example.com
- **Status Page**: https://status.phoenix.example.com

---

**Document Version**: 1.0  
**Last Updated**: 2026-02-27  
**Maintained By**: Phoenix API Team