Coding Agents

Integrate Phoenix with AI coding assistants using CLI, MCP, and skills in a single workflow guide.

Use this guide to connect coding agents (Claude Code, Cursor, VS Code, Windsurf, and others) to Phoenix for debugging, observability, and evaluation workflows.

Recommended Setup

Most users should set up all three:

CLI

Terminal access to traces, experiments, datasets, and prompts.

MCP

In-editor Phoenix documentation lookup and optional direct Phoenix instance operations.

Skills

Reusable instructions so agents apply Phoenix best practices consistently.

Shared Environment Configuration

Set environment variables to connect to your Phoenix instance:

export PHOENIX_HOST=http://localhost:6006    # Your Phoenix endpoint
export PHOENIX_PROJECT=my-project            # Project name
export PHOENIX_API_KEY=your-api-key          # API key (if auth enabled)

Keep API keys out of committed config files. Prefer environment variables and local-only config.

CLI

Install the Phoenix CLI globally:

npm install -g @arizeai/phoenix-cli

Use CLI tools when your coding agent needs terminal-native access to Phoenix resources, including traces, experiments, datasets, and prompts.

Common agent workflows with px:

• investigate trace failures and performance regressions
• inspect and compare experiment runs
• list and fetch datasets for evaluation workflows
• inspect and retrieve prompt versions and content

Example prompt:

Debug my agent's tool-call failures. Use Phoenix CLI to inspect traces, recent experiments, and relevant prompts, then summarize root causes.

Verify CLI installation:

px --help

MCP

MCP has two different Phoenix integrations, and they serve different goals.

MCP Integration	Purpose	When to use
Phoenix Docs MCP	Search Phoenix documentation from your coding agent	Recommended for all users
Phoenix MCP Server	Operate directly on your Phoenix instance (projects, traces, sessions, prompts, datasets, experiments, and more)	Use when you want agent-driven Phoenix data operations

Phoenix Docs MCP (Documentation Access)

Phoenix Docs MCP URL:

https://arizeai-433a7140.mintlify.app/mcp

Claude Code

Project scope:

claude mcp add --transport http phoenix-docs https://arizeai-433a7140.mintlify.app/mcp

User scope:

claude mcp add --transport http phoenix-docs --scope user https://arizeai-433a7140.mintlify.app/mcp

Verify:

claude mcp list

Cursor

Add to ~/.cursor/mcp.json (or project .cursor/mcp.json):

{
  "mcpServers": {
    "phoenix-docs": {
      "url": "https://arizeai-433a7140.mintlify.app/mcp"
    }
  }
}

Then restart Cursor and confirm the server appears in MCP settings.

VS Code

Use the Command Palette and run MCP: Add Server, or add the server to .vscode/mcp.json:

{
  "servers": {
    "phoenix-docs": {
      "url": "https://arizeai-433a7140.mintlify.app/mcp"
    }
  }
}

Then run MCP: List Servers in the Command Palette to verify.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "phoenix-docs": {
      "serverUrl": "https://arizeai-433a7140.mintlify.app/mcp"
    }
  }
}

Then refresh MCP servers from Windsurf MCP settings.

Reference docs: Claude Code MCP, Cursor MCP, VS Code MCP servers, Windsurf MCP.

Phoenix MCP Server (Direct Phoenix Operations)

For direct operations against your Phoenix instance (traces, sessions, prompts, datasets, experiments, and more), use the dedicated setup guide:

• /docs/phoenix/integrations/phoenix-mcp-server

Install both MCP integrations if you want your coding agent to both look up docs and perform direct Phoenix instance operations.

Skills

Install Phoenix skills using skills add:

npx skills add Arize-ai/phoenix

This installs skills into the project’s agent directory (for example, .claude/skills/, .cursor/skills/, or .github/skills/).

Available Skills

phoenix-cli

Debug LLM apps using Phoenix CLI for traces, experiments, datasets, and prompts. Recommended.

phoenix-evals

Build and run evaluators for AI/LLM apps across code-based and LLM-as-judge workflows.

phoenix-tracing

Implement OpenInference tracing conventions and instrumentation in Python and TypeScript.

skills add Options

Option	Description
-g, --global	Install to user directory instead of project
-a, --agent <agents...>	Target specific agents (for example, claude-code, cursor)
-s, --skill <skills...>	Install specific skills by name
-l, --list	List available skills without installing
-y, --yes	Skip confirmation prompts

Examples

# Install the CLI skill globally for all projects
npx skills add Arize-ai/phoenix --skill phoenix-cli -g

# Install CLI + tracing skills together
npx skills add Arize-ai/phoenix --skill phoenix-cli --skill phoenix-tracing

# Install for specific coding agents
npx skills add Arize-ai/phoenix --skill phoenix-cli -a claude-code -a cursor

# Non-interactive installation
npx skills add Arize-ai/phoenix --skill phoenix-cli -g -y

Supported agents include Claude Code, Cursor, Windsurf, Codex, GitHub Copilot, Cline, OpenCode, Gemini CLI, and 20+ more.

Recommended default:

npx skills add Arize-ai/phoenix --skill phoenix-cli --skill phoenix-tracing

Docs and Source Code in node_modules

Phoenix’s TypeScript packages ship docs and source code inside node_modules once installed. Coding agents can inspect version-matched docs, examples, and source code directly under node_modules, without relying on the public website.

Common paths:

node_modules/@arizeai/phoenix-client/docs/
node_modules/@arizeai/phoenix-client/src/

node_modules/@arizeai/phoenix-evals/docs/
node_modules/@arizeai/phoenix-evals/src/

node_modules/@arizeai/phoenix-otel/docs/
node_modules/@arizeai/phoenix-otel/src/

This means your agent can look up accurate API signatures, implementations, and usage examples directly from the installed package — ensuring it always uses the version of the SDK that’s actually installed in your project.

Related

CLI Reference

Full command reference for Phoenix CLI.

Retrieve Traces via CLI

Detailed guide for fetching traces from Phoenix.

Phoenix MCP Server

Interact with projects, traces, sessions, prompts, datasets, and experiments via the Phoenix MCP Server.