Coding Agents

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

This page sets up your coding agent to operate on Phoenix — reading traces, experiments, and datasets via the CLI, MCP, and skills. To instead trace your sessions with a coding agent (turns, tool calls, and token costs), see Coding Agents.

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

Phoenix offers a few MCP 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
`Remote MCP Server` (beta)	Operate directly on your Phoenix instance via the `/mcp` endpoint built into the server — no install	Primary choice for Phoenix data operations
`Phoenix MCP Server` (npm, maintenance mode)	Operate directly on your Phoenix instance via a local stdio `npx` server	Only with Phoenix versions that don’t serve `/mcp`

Phoenix Docs MCP (Documentation Access)

Phoenix Docs MCP URL:

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

Claude Code
Cursor
VS Code
Windsurf

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

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.

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.

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.

Direct Phoenix Operations (Remote MCP or npm)

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

Remote MCP Server (beta) — built into the Phoenix server, no install. The primary way to connect going forward.
Phoenix MCP Server — the @arizeai/phoenix-mcp npm package, in maintenance mode; for Phoenix versions without /mcp.

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.

CLI Reference

Full command reference for Phoenix CLI.

Retrieve Traces via CLI

Detailed guide for fetching traces from Phoenix.

MCP Servers

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

Trace your sessions with a coding agent — turns, tool calls, and token costs — with the coding-harness-tracing toolkit.

Get Started

Tracing

Evaluation

Datasets & Experiments

Prompts

Settings

Concepts

Resources

Coding Agents

Recommended Setup

CLI

MCP

Skills

Shared Environment Configuration

CLI

MCP

Phoenix Docs MCP (Documentation Access)

Direct Phoenix Operations (Remote MCP or npm)

Skills

Available Skills

phoenix-cli

phoenix-evals

phoenix-tracing

`skills add` Options

Examples

Docs and Source Code in `node_modules`

CLI Reference

Retrieve Traces via CLI

MCP Servers

Coding Agents

​Recommended Setup

CLI

MCP

Skills

​Shared Environment Configuration

​CLI

​MCP

​Phoenix Docs MCP (Documentation Access)

​Direct Phoenix Operations (Remote MCP or npm)

​Skills

​Available Skills

phoenix-cli

phoenix-evals

phoenix-tracing

​skills add Options

​Examples

​Docs and Source Code in node_modules

​Related

CLI Reference

Retrieve Traces via CLI

MCP Servers

Coding Agents

Recommended Setup

Shared Environment Configuration

CLI

MCP

Phoenix Docs MCP (Documentation Access)

Direct Phoenix Operations (Remote MCP or npm)

Skills

Available Skills

`skills add` Options

Examples

Docs and Source Code in `node_modules`

Related