---
title: "Coding Agents"
description: 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.

<Note>
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).
</Note>

## Recommended Setup

Most users should set up all three:

<CardGroup cols={3}>
  <Card title="CLI" icon="terminal" href="#cli">
    Terminal access to traces, experiments, datasets, and prompts.
  </Card>
  <Card title="MCP" icon="plug" href="#mcp">
    In-editor Phoenix documentation lookup and optional direct Phoenix instance operations.
  </Card>
  <Card title="Skills" icon="wand-magic-sparkles" href="#skills">
    Reusable instructions so agents apply Phoenix best practices consistently.
  </Card>
</CardGroup>

## Shared Environment Configuration

Set environment variables to connect to your Phoenix instance:

```bash
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)
```

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

## CLI

Install the Phoenix CLI globally:

```bash
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
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
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
https://arizeai-433a7140.mintlify.app/mcp
```

<Card>
  <Tabs>
    <Tab title="Claude Code">
      Project scope:

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

      User scope:

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

      Verify:

      ```bash
      claude mcp list
      ```
    </Tab>
    <Tab title="Cursor">
      Add to `~/.cursor/mcp.json` (or project `.cursor/mcp.json`):

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

      Then restart Cursor and confirm the server appears in MCP settings.
    </Tab>
    <Tab title="VS Code">
      Use the Command Palette and run `MCP: Add Server`, or add the server to `.vscode/mcp.json`:

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

      Then run `MCP: List Servers` in the Command Palette to verify.
    </Tab>
    <Tab title="Windsurf">
      Add to `~/.codeium/windsurf/mcp_config.json`:

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

      Then refresh MCP servers from Windsurf MCP settings.
    </Tab>
  </Tabs>
</Card>

<Note>
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).
</Note>

### 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.
- [Phoenix MCP Server](/docs/phoenix/integrations/phoenix-mcp-server) — the `@arizeai/phoenix-mcp` npm package, in maintenance mode; for Phoenix versions without `/mcp`.

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

## Skills

Install Phoenix skills using [skills add](https://github.com/vercel-labs/skills):

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

<CardGroup cols={3}>
  <Card title="phoenix-cli" href="https://github.com/Arize-ai/phoenix/blob/main/.agents/skills/phoenix-cli/SKILL.md">
    Debug LLM apps using Phoenix CLI for traces, experiments, datasets, and prompts. Recommended.
  </Card>
  <Card title="phoenix-evals" href="https://github.com/Arize-ai/phoenix/blob/main/.agents/skills/phoenix-evals/SKILL.md">
    Build and run evaluators for AI/LLM apps across code-based and LLM-as-judge workflows.
  </Card>
  <Card title="phoenix-tracing" href="https://github.com/Arize-ai/phoenix/blob/main/.agents/skills/phoenix-tracing/SKILL.md">
    Implement OpenInference tracing conventions and instrumentation in Python and TypeScript.
  </Card>
</CardGroup>

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

```bash
# 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
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
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

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="terminal" href="/docs/phoenix/sdk-api-reference/typescript/arizeai-phoenix-cli">
    Full command reference for Phoenix CLI.
  </Card>
  <Card title="Retrieve Traces via CLI" icon="download" href="/docs/phoenix/tracing/how-to-tracing/importing-and-exporting-traces/retrieve-traces-via-cli">
    Detailed guide for fetching traces from Phoenix.
  </Card>
  <Card title="MCP Servers" icon="plug" href="/docs/phoenix/integrations/mcp">
    Interact with projects, traces, sessions, prompts, datasets, and experiments via the Phoenix MCP servers.
  </Card>
  <Card title="Coding Agents" icon="terminal" href="/docs/phoenix/integrations/coding-agents/claude-code">
    Trace your sessions with a coding agent — turns, tool calls, and token costs — with the coding-harness-tracing toolkit.
  </Card>
</CardGroup>
