This guide explains how to install and use Orange MCP, the Phoenix Security MCP server that gives any MCP-capable agent conversational access to the ASPM platform.

1. Introduction

Orange MCP is a Model Context Protocol server for the Phoenix Security platform. Once connected, an AI agent can query and manage Phoenix Security data using plain language instead of calling the REST API directly.

1.1 What it does

Orange MCP covers Phoenix REST API Enterprise v1.28, exposing 35 tools across two categories:

• Read tools (16): search findings and assets, read application and component risk posture, list teams and users, read campaign statistics, inspect API gaps.
• Write tools (19): create and update assets, enrich findings, manage applications, components, teams and users.

1.1.1 Read vs Write Tools

Write tools are disabled by default. Set “PHOENIX_MCP_READ_ONLY=true” to keep the connection read-only until you are ready to allow the agent to make changes. See section 6.1.

2. Requirements

• Python 3.10 or newer (python3 –version)
• uv, install with: curl -LsSf https://astral.sh/uv/install.sh | sh
• Phoenix API credentials (Settings > Organization > API Access). The client secret is shown once at creation; store it in a secrets manager, not in a plain file inside a repository.

3. Installation

3.1 Get the Code

git clone https://github.com/Security-Phoenix-demo/Pheonix-Security-Orange-MCP.git
cd Pheonix-Security-Orange-MCP

3.2 Create a Virtual Environment

This installs Orange MCP in editable mode along with its test dependencies.

uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

3.3 Verify Install

All tests run against mocked HTTP. Expect to see tests/test_server.py ….. (one dot per passing test) followed by a summary like 9 passed.

pytest

4. Configuration

4.1 API Credentials

Create a client ID/Secret pair in the Phoenix platform UI under Settings > Organization > API Access before continuing.

4.2 Environment Variables

• PHOENIX_CLIENT_ID: required. API client ID.
• PHOENIX_CLIENT_SECRET: required. API client secret.
• PHOENIX_API_BASE_URL: required. Demo, PoC and dedicated tenants use their own subdomain.
• PHOENIX_MCP_READ_ONLY: optional. Set to true to disable all 19 write tools.
• PHOENIX_MCP_MAX_ITEMS: optional. Caps list-result size, default 100.

4.3 Registering with Claude Code

claude mcp add orange-mcp --scope user \
  -e PHOENIX_CLIENT_ID="your-client-id" \
  -e PHOENIX_CLIENT_SECRET="your-client-secret" \
  -e PHOENIX_API_BASE_URL="your-full-api-url" \
  -e PHOENIX_MCP_READ_ONLY=true \
  -- "$(pwd)/.venv/bin/phoenix-mcp"

–scope user makes the server available in every project. Run this from inside the repository with the virtual environment activated so $(pwd)/.venv/bin/phoenix-mcp resolves correctly.

Verify with: claude mcp list

This should display orange-mcp as Connected. MCP servers only load at session start, so open a new Claude Code session before trying the prompts in section 5.

5. Usage

Orange MCP is conversational: there is no command syntax to learn, the agent selects the right tool based on what you ask.

5.1 Example Prompts

• “Test the phoenix connection”: calls phoenix_test_connection.
• “List my Phoenix applications and their risk posture”: calls phoenix_list_applications and phoenix_get_application_posture.
• “Which applications have open critical findings breaching SLA? Summarise by team”: calls phoenix_search_findings.
• “Find all container assets tagged env:prod”: calls phoenix_search_assets.
• “Show me the risk posture for the payments component”: calls phoenix_get_component_posture.
• “List teams and their members”: calls phoenix_list_teams and phoenix_get_team_members.
• “Get the stats for campaign <id>”: calls phoenix_get_campaign_stats.

5.1.1 Write Operations

Write prompts require PHOENIX_MCP_READ_ONLY to be unset. Examples:

• “Create a CONTAINER asset for myorg/api:2.1 tagged env:prod and link the org/api repository to the Payments application.”
• “Enrich CVE-2024-3094 findings with a triage note and raise their severity to 9.8.”

With read-only mode on, these correctly fail with a read-only error rather than silently doing nothing.

5.2 Handling API Gaps

Some operations are not supported by the Phoenix API (per-finding status updates or asset deletion).

Ask “What can’t the Phoenix API do right now, and what are the workarounds?” to call phoenix_api_gaps, or use phoenix_raw_api as an authenticated escape hatch for any /v1 endpoint without a dedicated tool.

6. Best Practices & Recommendations

6.1 Start in Read-Only Mode

Set PHOENIX_MCP_READ_ONLY=true when first connecting a new environment or credential. Remove it only once you are comfortable letting the agent create and modify data.

6.2 Avoid Server Name Collisions

Do not register this server as “phoenix-security”. That name is already used by an unrelated org-wide connector (CVE intelligence, EOL tracking, supply-chain firewall). If the names collide, new sessions may silently connect to the wrong tool set. Use orange-mcp or another distinct name.