Coding Agents

Use this guide to connect coding agents (Claude Code, Codex, Cursor, VS Code, Windsurf, and others) to Phoenix for debugging, observability, and evaluation workflows. If you haven’t instrumented your app yet, start with Agent-Assisted Setup.

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

Phoenix connects to a coding agent through three pieces. Most setups use 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.

How you install them depends on your agent. For agents that have a plugin system, the Phoenix repository is also a plugin marketplace, and the plugin is the fastest way to set up the MCP server (and, for Claude Code, the skills):

Claude Code — install the Phoenix plugin. It registers the Phoenix MCP server and the phoenix-cli, phoenix-evals, and phoenix-tracing skills, so the only piece left to add is the CLI.
Codex — install the Phoenix plugin. It registers the Phoenix MCP server; add the CLI and skills yourself.
Every other agent (Cursor, VS Code, Windsurf, and more) — follow the CLI, MCP, and Skills sections below.

Both plugins connect to the MCP endpoint built into the Phoenix server, which requires Phoenix 19.0.0 or later. Neither includes the Phoenix Docs MCP for documentation lookup — add that separately if you want it.

The plugins are optional. You don’t have to add a marketplace to use Phoenix from Claude Code or Codex. If you’d rather not, or want only some of the pieces, install them individually: the CLI, MCP, and Skills sections below work for Claude Code and Codex exactly as they do for every other agent. The plugin just bundles the MCP and skills steps into one install that stays up to date.

Find Your Phoenix Endpoint

Every setup on this page needs the endpoint of your Phoenix instance: the base URL you open Phoenix at in the browser, with no trailing slash and no path such as /mcp or /v1. Go to the Settings page in your Phoenix instance to find your endpoint and, if auth is enabled, to create an API key.

Deployment	Endpoint	MCP server URL the tools derive from it
Local Phoenix (`phoenix serve`)	`http://localhost:6006`	`http://localhost:6006/mcp`
Deployed Phoenix	`https://phoenix.example.com` (your deployment’s hostname)	`https://phoenix.example.com/mcp`

Enter the endpoint column, never the /mcp column — the plugins and the px CLI append /mcp themselves. A local Phoenix works with the defaults everywhere below; the API key is only required when auth is enabled.

Claude Code

The Phoenix repository is a Claude Code plugin marketplace. The arize-phoenix plugin registers the Phoenix MCP server and the Phoenix skills in one install, and because the marketplace is versioned in the repository, Claude Code updates both as new versions land. Using the plugin is optional. To set things up piece by piece instead — or to skip the marketplace entirely — register the MCP server by hand with claude mcp add as shown on the Remote MCP Server page, and add skills with skills add. The result is the same; the plugin only saves the steps and keeps them updated. Prerequisites: Phoenix 19.0.0 or later, and a current Claude Code — if /plugin is not recognized, update Claude Code first. Steps 1, 2, and 4 are slash commands typed inside a Claude Code session; the shell equivalents follow the steps.

Install the Plugin

Add the marketplace

Inside a Claude Code session, run:

/plugin marketplace add Arize-ai/phoenix

The owner/repo shorthand and the full https://github.com/Arize-ai/phoenix URL both work. Adding a marketplace registers the catalog; it installs nothing on its own.

Install the plugin

/plugin install arize-phoenix@arize-phoenix

Claude Code asks for a scope: user for all your projects, project to share it with collaborators through .claude/settings.json, or local for this repository only.

Set your Phoenix endpoint

Claude Code prompts for one setting, Phoenix endpoint, as it enables the plugin. Enter your Phoenix endpoint — the base URL only, with no trailing slash — or keep the default http://localhost:6006 for a local Phoenix. The plugin appends /mcp itself:

You enter	The plugin connects to
`http://localhost:6006` (default)	`http://localhost:6006/mcp`
`https://phoenix.example.com`	`https://phoenix.example.com/mcp`

A trailing slash or a pasted /mcp produces a wrong URL (…//mcp or …/mcp/mcp), so trim those off. This setting is stored in your user settings and applies to every project; see Change the Endpoint to update it later.

Verify

Run /mcp and select phoenix. If your Phoenix has auth enabled, a browser window opens to sign in with your Phoenix account; without auth, it connects straight away. The server is ready once /mcp shows it as connected.To see everything the plugin added — the MCP server and the three skills — run claude plugin details arize-phoenix@arize-phoenix in your shell. It also reports what the plugin adds to your context window.

To script the install instead, run the shell equivalents claude plugin marketplace add Arize-ai/phoenix and claude plugin install arize-phoenix@arize-phoenix. They install to user scope unless you pass --scope project or --scope local, and take effect the next time you start Claude Code (or after /reload-plugins in an open session).

What the Plugin Registers

Component	What it is
`phoenix` MCP server	Streamable HTTP to `<your-endpoint>/mcp` — the Remote MCP Server built into Phoenix 19.0.0 and later.
`phoenix-cli` skill	Fetching traces, inspecting datasets and experiments, and querying GraphQL with the `px` CLI.
`phoenix-evals` skill	Building and running evaluators.
`phoenix-tracing` skill	Instrumenting apps with OpenInference.

These are the same skills described under Skills, so you don’t need skills add for them in Claude Code. Two things the plugin does not include: the px CLI, which the phoenix-cli skill needs on your PATH, and the Phoenix Docs MCP — add either separately.

Change the Endpoint

To set the endpoint non-interactively at install time:

claude plugin install arize-phoenix@arize-phoenix --config endpoint=https://phoenix.example.com

To change it afterward, run /plugin configure inside Claude Code, or edit pluginConfigs in your user settings (~/.claude/settings.json):

{
  "pluginConfigs": {
    "arize-phoenix@arize-phoenix": {
      "options": { "endpoint": "https://phoenix.example.com" }
    }
  }
}

This setting configures the MCP server only. The px CLI that the phoenix-cli skill drives reads PHOENIX_ENDPOINT and PHOENIX_API_KEY from your shell, so export those as well — see Shared Environment Configuration.

Authentication

When your Phoenix has auth enabled, the plugin’s MCP server signs in with OAuth in the browser the first time you use it; the plugin has no slot for an API key. When Phoenix runs without auth, no login happens. For a headless environment where no browser can open — CI, a remote machine — don’t use the plugin’s server. Register one that sends your API key as a bearer token instead:

px setup mcp --agent claude --header 'Authorization: Bearer ${PHOENIX_API_KEY}'

Both register a server named phoenix, so pick one: uninstall or disable the plugin before running px setup mcp. The skills can still be installed with skills add.

Update, Remove, or Develop Locally

claude plugin update arize-phoenix@arize-phoenix     # pull the latest version
claude plugin uninstall arize-phoenix@arize-phoenix  # remove the plugin

To work on the plugin itself, add the marketplace from a checkout with /plugin marketplace add ./ at the repository root — note the ./, since a bare . is rejected — and check your changes with claude plugin validate plugins/claude/arize-phoenix. The catalog is .claude-plugin/marketplace.json and the plugin lives in plugins/claude/arize-phoenix.

Codex

The same repository is a Codex plugin marketplace. The arize-phoenix plugin registers the Phoenix MCP server in Codex. It does not ship skills — add those with skills add, passing -a codex. Using the plugin is optional. To skip the marketplace, add the MCP server to ~/.codex/config.toml by hand as shown on the Remote MCP Server page, and install the CLI and skills individually. Prerequisites: Phoenix 19.0.0 or later, and Node.js — the plugin starts its MCP bridge with npx. The codex plugin commands below run in your shell.

Install the Plugin

Add the marketplace

codex plugin marketplace add Arize-ai/phoenix

Codex clones the repository and reads the catalog from .agents/plugins/marketplace.json. The source can be owner/repo shorthand, owner/repo@ref, an HTTPS or SSH Git URL, or a local path; pass --ref to pin a Git ref.

Install the plugin

codex plugin add arize-phoenix@arize-phoenix

Codex caches the plugin under ~/.codex/plugins/cache/arize-phoenix/arize-phoenix/<version> and enables it in ~/.codex/config.toml. You can also browse and install from the /plugins browser inside Codex.

Export your Phoenix endpoint

The Codex plugin has no settings dialog; it reads your Phoenix endpoint from PHOENIX_ENDPOINT — the same variable the px CLI reads. Export it, and your API key if auth is enabled, in the shell you launch Codex from:

export PHOENIX_ENDPOINT=https://phoenix.example.com   # base URL only; the plugin appends /mcp
export PHOENIX_API_KEY=your-api-key                   # only if auth is enabled

Leave PHOENIX_ENDPOINT unset for a local Phoenix; it defaults to http://localhost:6006. The variables must be set in the environment you start codex from, and Codex forwards to the plugin only these two, which are the ones it declares.

Verify

codex mcp list

The phoenix server appears as enabled. Then launch codex and run /mcp to confirm it connects. If your Phoenix has auth enabled and PHOENIX_API_KEY is not set, a browser window opens on first use to sign in with your Phoenix account; with the key set, or with auth disabled, no login happens.

How It Connects

Codex plugin MCP entries cannot contain environment variables in the URL, so instead of pointing at <endpoint>/mcp directly, the plugin registers a small stdio launcher, scripts/phoenix-mcp. The launcher reads your environment and bridges to the Remote MCP Server at <PHOENIX_ENDPOINT>/mcp with mcp-remote via npx.

Variable	Effect
`PHOENIX_ENDPOINT`	Your Phoenix endpoint. The launcher strips a trailing slash and appends `/mcp`, and leaves a value that already ends in `/mcp` alone, so `https://phoenix.example.com`, `https://phoenix.example.com/`, and `https://phoenix.example.com/mcp` all connect to the same server. Defaults to `http://localhost:6006`.
`PHOENIX_API_KEY`	Optional. When set, requests carry it as a bearer token and no browser login is needed. The launcher passes `mcp-remote` an unexpanded `${PHOENIX_API_KEY}` reference that it resolves from its own environment, so the key never appears in process arguments.

Enable, Disable, or Remove

Installing writes an entry to ~/.codex/config.toml. Set enabled = false to turn the plugin off without uninstalling it:

[plugins."arize-phoenix@arize-phoenix"]
enabled = true

codex plugin marketplace upgrade arize-phoenix   # refresh the catalog snapshot
codex plugin remove arize-phoenix@arize-phoenix  # uninstall and clear the cache
codex plugin marketplace remove arize-phoenix    # drop the marketplace

To work on the plugin itself, add the marketplace from a checkout with codex plugin marketplace add . at the repository root. The catalog is .agents/plugins/marketplace.json and the plugin lives in plugins/codex/arize-phoenix.

Shared Environment Configuration

Set environment variables to connect to your Phoenix instance. PHOENIX_ENDPOINT is your Phoenix endpoint — the base URL, with no path:

export PHOENIX_ENDPOINT=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. In Claude Code and Codex, the Phoenix plugin registers this server for you.
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/). In Claude Code, the Phoenix plugin already registers the phoenix-cli, phoenix-evals, and phoenix-tracing skills, so installing it covers those.

Available Skills

phoenix-cli

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

phoenix-error-analysis

Read sampled traces, write free-form notes, then group them into a failure taxonomy that picks eval targets and fix priorities.

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.

phoenix-harbor

Configure Harbor agent evaluations and interpret their Phoenix experiments, scores, and ATIF traces.

`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.

​Recommended Setup

CLI

MCP

Skills

​Find Your Phoenix Endpoint

​Claude Code

​Install the Plugin

​What the Plugin Registers

​Change the Endpoint

​Authentication

​Update, Remove, or Develop Locally

​Codex

​Install the Plugin

​How It Connects

​Enable, Disable, or Remove

​Shared Environment Configuration

​CLI

​MCP

​Phoenix Docs MCP (Documentation Access)

​Direct Phoenix Operations (Remote MCP or npm)

​Skills

​Available Skills

phoenix-cli

phoenix-error-analysis

phoenix-evals

phoenix-tracing

phoenix-harbor

​skills add Options

​Examples

​Docs and Source Code in node_modules

​Related

CLI Reference

Retrieve Traces via CLI

MCP Servers

Coding Agents

Recommended Setup

Find Your Phoenix Endpoint

Claude Code

Install the Plugin

What the Plugin Registers

Change the Endpoint

Authentication

Update, Remove, or Develop Locally

Codex

Install the Plugin

How It Connects

Enable, Disable, or Remove

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