> ## Documentation Index > Fetch the complete documentation index at: https://arizeai-433a7140-ehutt-trail-benchmark-new-tasks.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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, 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](/docs/phoenix/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](/docs/phoenix/integrations/coding-agents/claude-code). ## Recommended Setup Phoenix connects to a coding agent through three pieces. Most setups use all three: Terminal access to traces, experiments, datasets, and prompts. In-editor Phoenix documentation lookup and optional direct Phoenix instance operations. 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](#claude-code). 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](#cli). * **Codex** — install the [Phoenix plugin](#codex). It registers the Phoenix MCP server; add the [CLI](#cli) and [skills](#skills) yourself. * **Every other agent** (Cursor, VS Code, Windsurf, and more) — follow the [CLI](#cli), [MCP](#mcp), and [Skills](#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](#phoenix-docs-mcp-documentation-access) 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](#cli), [MCP](#mcp), and [Skills](#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](https://code.claude.com/docs/en/discover-plugins). 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](/docs/phoenix/integrations/remote-mcp) page, and add skills with [`skills add`](#skills). 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 Inside a Claude Code session, run: ```bash theme={null} /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. ```bash theme={null} /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. Claude Code prompts for one setting, **Phoenix endpoint**, as it enables the plugin. Enter [your Phoenix endpoint](#find-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](#change-the-endpoint) to update it later. 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 `/mcp` — the [Remote MCP Server](/docs/phoenix/integrations/remote-mcp) 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](#skills), so you don't need `skills add` for them in Claude Code. Two things the plugin does **not** include: the [`px` CLI](#cli), which the `phoenix-cli` skill needs on your `PATH`, and the [Phoenix Docs MCP](#phoenix-docs-mcp-documentation-access) — add either separately. ### Change the Endpoint To set the endpoint non-interactively at install time: ```bash theme={null} 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`): ```json theme={null} { "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](#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: ```bash theme={null} 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`](#skills). ### Update, Remove, or Develop Locally ```bash theme={null} 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`](https://github.com/Arize-ai/phoenix/blob/main/.claude-plugin/marketplace.json) and the plugin lives in [`plugins/claude/arize-phoenix`](https://github.com/Arize-ai/phoenix/tree/main/plugins/claude/arize-phoenix). ## Codex The same repository is a [Codex plugin marketplace](https://developers.openai.com/plugins/build/plugins#add-a-marketplace-from-the-cli). The `arize-phoenix` plugin registers the Phoenix MCP server in Codex. It does not ship skills — add those with [`skills add`](#skills), 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](/docs/phoenix/integrations/remote-mcp) page, and install the [CLI](#cli) and [skills](#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 ```bash theme={null} 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. ```bash theme={null} codex plugin add arize-phoenix@arize-phoenix ``` Codex caches the plugin under `~/.codex/plugins/cache/arize-phoenix/arize-phoenix/` and enables it in `~/.codex/config.toml`. You can also browse and install from the `/plugins` browser inside Codex. The Codex plugin has no settings dialog; it reads [your Phoenix endpoint](#find-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: ```bash theme={null} 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. ```bash theme={null} 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 `/mcp` directly, the plugin registers a small stdio launcher, [`scripts/phoenix-mcp`](https://github.com/Arize-ai/phoenix/blob/main/plugins/codex/arize-phoenix/scripts/phoenix-mcp). The launcher reads your environment and bridges to the [Remote MCP Server](/docs/phoenix/integrations/remote-mcp) at `/mcp` with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) via `npx`. | Variable | Effect | | - | - | | `PHOENIX_ENDPOINT` | [Your Phoenix endpoint](#find-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: ```toml theme={null} [plugins."arize-phoenix@arize-phoenix"] enabled = true ``` ```bash theme={null} 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`](https://github.com/Arize-ai/phoenix/blob/main/.agents/plugins/marketplace.json) and the plugin lives in [`plugins/codex/arize-phoenix`](https://github.com/Arize-ai/phoenix/tree/main/plugins/codex/arize-phoenix). ## Shared Environment Configuration Set environment variables to connect to your Phoenix instance. `PHOENIX_ENDPOINT` is [your Phoenix endpoint](#find-your-phoenix-endpoint) — the base URL, with no path: ```bash theme={null} 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: ```bash theme={null} 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: ```text theme={null} 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: ```bash theme={null} 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`](/docs/phoenix/integrations/remote-mcp) (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: ```text theme={null} https://arizeai-433a7140.mintlify.app/mcp ``` Project scope: ```bash theme={null} claude mcp add --transport http phoenix-docs https://arizeai-433a7140.mintlify.app/mcp ``` User scope: ```bash theme={null} claude mcp add --transport http phoenix-docs --scope user https://arizeai-433a7140.mintlify.app/mcp ``` Verify: ```bash theme={null} claude mcp list ``` Add to `~/.cursor/mcp.json` (or project `.cursor/mcp.json`): ```json theme={null} { "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`: ```json theme={null} { "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`: ```json theme={null} { "mcpServers": { "phoenix-docs": { "serverUrl": "https://arizeai-433a7140.mintlify.app/mcp" } } } ``` Then refresh MCP servers from Windsurf MCP settings. Reference docs: [Claude Code MCP](https://docs.anthropic.com/en/docs/claude-code/mcp), [Cursor MCP](https://docs.cursor.com/context/model-context-protocol), [VS Code MCP servers](https://code.visualstudio.com/docs/copilot/chat/mcp-servers), [Windsurf MCP](https://docs.windsurf.com/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](/docs/phoenix/integrations/remote-mcp) (beta) — built into the Phoenix server, no install. The primary way to connect going forward. In [Claude Code](#claude-code) and [Codex](#codex), the Phoenix plugin registers this server for you. * [Phoenix MCP Server](/docs/phoenix/integrations/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](https://github.com/vercel-labs/skills): ```bash theme={null} 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](#claude-code) already registers the `phoenix-cli`, `phoenix-evals`, and `phoenix-tracing` skills, so installing it covers those. ### Available Skills Debug LLM apps using Phoenix CLI for traces, experiments, datasets, and prompts. Recommended. Read sampled traces, write free-form notes, then group them into a failure taxonomy that picks eval targets and fix priorities. Build and run evaluators for AI/LLM apps across code-based and LLM-as-judge workflows. Implement OpenInference tracing conventions and instrumentation in Python and TypeScript. 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 ` | Target specific agents (for example, `claude-code`, `cursor`) | | `-s, --skill ` | Install specific skills by name | | `-l, --list` | List available skills without installing | | `-y, --yes` | Skip confirmation prompts | ### Examples ```bash theme={null} # 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](https://github.com/vercel-labs/skills#supported-agents). Recommended default: ```bash theme={null} 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: ```text theme={null} 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 Full command reference for Phoenix CLI. Detailed guide for fetching traces from Phoenix. 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.