> ## Documentation Index
> Fetch the complete documentation index at: https://arizeai-433a7140-roger-ci-skip-release-prs.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, 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).

<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 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
https://arizeai-433a7140.mintlify.app/mcp
```

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

      ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
      claude mcp add --transport http phoenix-docs https://arizeai-433a7140.mintlify.app/mcp
      ```

      User scope:

      ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
      claude mcp add --transport http phoenix-docs --scope user https://arizeai-433a7140.mintlify.app/mcp
      ```

      Verify:

      ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
      claude mcp list
      ```
    </Tab>

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

      ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
      {
        "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 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
      {
        "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 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
      {
        "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 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
# 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={"theme":{"light":"github-light-default","dark":"github-dark-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:

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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>