> ## Documentation Index
> Fetch the complete documentation index at: https://arizeai-433a7140.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# @arizeai/phoenix-mcp

> MCP server implementation for Arize Phoenix providing unified interface to Phoenix's capabilities.

<a href="https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-mcp/LICENSE">
  <img src="https://storage.googleapis.com/arize-phoenix-assets/assets/images/phoenix-docs-images/db18c3fa-image.svg" className="inline" />
</a>

<img src="https://storage.googleapis.com/arize-phoenix-assets/assets/images/phoenix-docs-images/b0780182-image.svg" className="inline" />

<Card horizontal title="phoenix/js/packages/phoenix-mcp at main · Arize-ai/phoenix" href="https://github.com/Arize-ai/phoenix/tree/main/js/packages/phoenix-mcp" icon="github">
  Github
</Card>

Phoenix MCP Server is an implementation of the Model Context Protocol for the Arize Phoenix platform. It provides a unified interface to Phoenix's capabilities.

You can use Phoenix MCP Server for:

* **Projects Management**: List and explore projects that organize your observability data

* **Traces, Spans & Annotations**: Retrieve traces, spans, and annotation configs for analysis and debugging

* **Sessions**: Explore conversation flows and session-level annotations

* **Prompts Management**: Create, list, update, and iterate on prompts

* **Datasets**: Explore datasets and synthesize new examples

* **Experiments**: Pull experiment results and visualize them with the help of an LLM

Don't see a use-case covered? `@arizeai/phoenix-mcp` is [open-source](https://github.com/Arize-ai/phoenix)! Issues and PRs welcome.

## Installation

```bash theme={null}
npm i @arizeai/phoenix-mcp
```

This MCP server can be used using `npx` and can be directly integrated with clients like Claude Desktop, Cursor, and more.

```json theme={null}
{
  "mcpServers": {
    "phoenix": {
      "command": "npx",
      "args": [
        "-y",
        "@arizeai/phoenix-mcp@latest",
        "--baseUrl",
        "https://my-phoenix.com",
        "--apiKey",
        "your-api-key"
      ]
    }
  }
}
```

## Development

### Install

This package is managed via a pnpm workspace.

```bash theme={null}
// From the /js/ directory
pnpm install
pnpm build
```

This only needs to be repeated if dependencies change or there is a change to the phoenix-client.

#### Building

To build the project:

```bash theme={null}
pnpm build
```

#### Development Mode

To run in development mode:

```bash theme={null}
pnpm dev
```

#### Debugging

You can build and run the MCP inspector using the following:

```bash theme={null}
pnpm inspect
```

### Environment Variables

When developing, the server requires the following environment variables:

* `PHOENIX_API_KEY`: Your Phoenix API key

* `PHOENIX_HOST`: The base URL for Phoenix

* `PHOENIX_PROJECT`: Optional default project for project-scoped tools

* `PHOENIX_CLIENT_HEADERS`: Optional JSON-encoded request headers

Make sure to set these in a `.env` file. See `.env.example`.

## Tool Coverage

The MCP server covers the main operational Phoenix workflows:

**Prompts** — `list-prompts`, `get-prompt`, `get-latest-prompt`, `get-prompt-by-identifier`, `get-prompt-version`, `list-prompt-versions`, `get-prompt-version-by-tag`, `list-prompt-version-tags`, `add-prompt-version-tag`, `upsert-prompt`

**Projects** — `list-projects`, `get-project`

**Traces** — `list-traces`, `get-trace`

**Spans** — `get-spans`, `get-span-annotations`

**Sessions** — `list-sessions`, `get-session`

**Annotation Configs** — `list-annotation-configs`

**Datasets** — `list-datasets`, `get-dataset`, `get-dataset-examples`, `get-dataset-experiments`, `add-dataset-examples`

**Experiments** — `list-experiments-for-dataset`, `get-experiment-by-id`

## License

Apache 2.0