Arize Phoenix MCP server: 27 tools for traces

Phoenix exposes traces and evaluations for your own agents, and it reaches the traces themselves, which most evaluation connectors do not.

Last verified 1 September 2026 · from Arize's repository, its documentation and the server's own tools/list response

This page is one of 90 in a directory of monitoring and developer tools. Each page checks what an AI coding agent can get out of the tool through its MCP server, the connector that lets the agent query the tool directly.

What is the Arize Phoenix MCP server?

It is Arize's server for the Model Context Protocol. Phoenix records what your own LLM applications did, so the agent gains tools for reading those traces, spans and sessions back.

The 27 tools group into four areas: prompts and their versions, projects with traces and spans, datasets and experiments, and annotation configuration. The trace tools are what distinguish it from evaluation-only connectors.

Phoenix is open source and self-hostable, and the same server points at either a self-hosted instance or Phoenix Cloud through PHOENIX_ENDPOINT.

Phoenix covers agent observability broadly, reaches part of the way into release through prompt versioning, and reaches nothing in code review, production observability or cost.

In practice, Phoenix answers questions about what your LLM application did, step by step, and nothing about the systems it ran on. An agent connected here can pull the trace behind a bad answer, read every span in it, and check how it scored. It cannot tell you the retrieval service was slow, so this connector pairs with an infrastructure one.

What can an AI agent do with Arize Phoenix?

What connecting costs before the first question

A context window is the amount of text a model can hold at once, and connecting uses some of it before the agent asks anything. Every tool the server registers sends its name, description and input schema to the model when the session starts. The tool list is charged whether or not a single tool is called.

Phoenix is efficient for its reach: 27 tools for about 4,769 tokens, which is less than LangSmith's 15 tools cost and less than Helicone's 2 cost. Its descriptions average 417 characters, short enough that the tool count, not the description length, drives the figure.

Encodings: GPT-5.6, GPT-5.5 o200k_base; GPT-4, GPT-3.5 cl100k_base; Claude Haiku 4.5 to Opus 5 count_tokens. Counted 21 August 2026 from tools/list on the published @arizeai/phoenix-mcp package. It was run locally with a placeholder URL and key.

Registration is static, so no Phoenix instance was involved. Figures cover name, description and input schema. The two models in column one share the o200k_base encoding, so they get one count. The spread is formatting, about 33%. Reasoning tokens are output, spent per request. This count is input, charged once at connection.

The Claude figures are measured rather than encoded. Anthropic publishes no local tokenizer. The definitions were sent to the API's count_tokens endpoint, and a no-tools baseline was subtracted. The range covers two tokenizer generations rather than two serializations. Haiku 4.5 and Opus 4.6 sit at the low end. Opus 5 and Sonnet 5 sit at the high end. The gap between them is about a third.

Can Arize Phoenix watch your own AI agents?

Phoenix is an agent-observability product, so this table asks how much of that surface the connector actually reaches. Counted from the server's own tools/list response on 21 August 2026.

Arize Phoenix MCP server limits: where answers come back incomplete

The limits below follow from how Phoenix scopes data rather than from anything failing.

How to configure Arize Phoenix MCP for agents

1. 1

   Set a default project

   PHOENIX_PROJECT scopes the trace and span tools. Without it the agent must name a project in every call, and a wrong name returns an empty result rather than an error.

2. 2

   Point at the right Phoenix

   PHOENIX_ENDPOINT selects Phoenix Cloud or your self-hosted instance, which is what makes this connector usable where hosted-only tools are not.

3. 3

   Allowlist read tools

   Three of the twenty-seven write, and moving a prompt tag changes which prompt version production resolves, if your application looks prompts up by tag.

4. 4

   Budget the context

   Twenty-seven tools cost about 4,769 tokens, roughly 2.4% of a 200,000-token window, which is cheap for the reach.

Paste this into your agent’s instructions

Phoenix scopes almost everything to a project, so its silent failure is a query against the wrong one. The block makes the agent name the project alongside any negative answer.

When you answer using Phoenix MCP tools, state:
- The project you queried, and the time range.
- How many traces or spans you retrieved against the limit
  you asked for.
- Whether a span carried annotations. An unannotated span has
  not been scored, which is not the same as scoring badly.
Never state that data does not exist. State that none was
returned under the constraints above.
Write your answer in ASD-STE100 Simplified Technical
English. Use short sentences with one idea in each.

Do you need the MCP server at all?

Not always. Phoenix has a documented REST API and Python client, and a coding agent can call either with the same key.

The connector's advantage is trace navigation. The agent calls list-projects to fix the scope, then list-traces, then get-spans, then get-span-annotations. Tool descriptions let it make those calls in the right order without being told the shape of the data.

Because Phoenix is self-hostable, the connector is also usable where a hosted-only agent-observability tool would not be an option at all.

Connect the server for open-ended trace investigation. Use the client library for scripted evaluation runs.

Arize Phoenix MCP server setup

The package runs with npx and needs PHOENIX_ENDPOINT plus an API key in PHOENIX_API_KEY. PHOENIX_PROJECT sets a default project for the project-scoped tools.

The same package works against Phoenix Cloud or a self-hosted Phoenix; only the base URL changes.

claude mcp add-json "phoenix" '{"command":"npx",
  "args":["-y","@arizeai/phoenix-mcp"],
  "env":{"PHOENIX_ENDPOINT":"https://app.phoenix.arize.com",
         "PHOENIX_API_KEY":"<your-key>",
         "PHOENIX_PROJECT":"<your-project>"}}'

{"mcpServers":{"phoenix":{"command":"npx",
  "args":["-y","@arizeai/phoenix-mcp"],
  "env":{"PHOENIX_ENDPOINT":"https://app.phoenix.arize.com",
         "PHOENIX_API_KEY":"<your-key>"}}}}

[mcp_servers.phoenix]
command = "npx"
args = ["-y", "@arizeai/phoenix-mcp"]
env = { PHOENIX_ENDPOINT = "https://app.phoenix.arize.com", PHOENIX_API_KEY = "<your-key>" }

Every other client

Each block below is the configuration for one client, with the file path and the key that client expects.

{"mcpServers":{"phoenix":{"command":"npx",
  "args":["-y","@arizeai/phoenix-mcp"],
  "env":{"PHOENIX_ENDPOINT":"https://app.phoenix.arize.com","PHOENIX_API_KEY":"<your-key>"}}}}

{"mcpServers":{"phoenix":{"command":"npx",
  "args":["-y","@arizeai/phoenix-mcp"],
  "env":{"PHOENIX_ENDPOINT":"https://app.phoenix.arize.com","PHOENIX_API_KEY":"<your-key>"}}}}

{"servers":{"phoenix":{"command":"npx",
  "args":["-y","@arizeai/phoenix-mcp"],
  "env":{"PHOENIX_ENDPOINT":"https://app.phoenix.arize.com","PHOENIX_API_KEY":"<your-key>"}}}}

{"mcpServers":{"phoenix":{"command":"npx",
  "args":["-y","@arizeai/phoenix-mcp"],
  "env":{"PHOENIX_ENDPOINT":"https://app.phoenix.arize.com","PHOENIX_API_KEY":"<your-key>"}}}}

PHOENIX_ENDPOINT=http://phoenix.internal:6006 \
PHOENIX_API_KEY=<your-key> \
npx -y @arizeai/phoenix-mcp

Read-only access, permissions and security

• Three of twenty-seven tools write

  upsert-prompt, add-prompt-version-tag and add-dataset-examples change Phoenix state, and there is no server-side read-only mode.

• Tagging a prompt version can be a production change

  If your application resolves prompts by tag at run time, moving a tag changes behavior without a deploy.

• Traces contain your users' inputs

  Phoenix stores prompts and completions, so an agent reading spans is reading whatever your application processed.

• Self-hosting keeps that data in your infrastructure

  That is the practical reason to prefer it over the hosted option for sensitive workloads.

Troubleshooting

No traces found for a project with traffic

Trace tools are project-scoped. Set PHOENIX_PROJECT, or have the agent name the project in each call and state which one it used.

A span has no annotations

That span has not been scored. The connector reads annotations rather than running evaluations, so an absent annotation is unscored, not a poor score.

401 or 403 on connect

PHOENIX_API_KEY is missing or scoped to another instance. Check PHOENIX_ENDPOINT points at the Phoenix that issued the key.

A prompt change appeared in production

upsert-prompt and add-prompt-version-tag are writes with no read-only mode. Remove them from your client's allowlist.

Arize Phoenix MCP server: Reference

What engineers report

Phoenix's connector ships inside the main project, so its signals are the platform's rather than a standalone repository's.

Repository facts from the GitHub API, retrieved 21 August 2026. Tool counts come from the server's own tools/list response on the published npm package.

Should you connect an agent to Arize Phoenix?

Yes. Best for phoenix teams allowlisting read tools and setting a default project.

Strongest fit

Teams on Phoenix who want an agent following a trace to its spans and annotations, especially where Phoenix is self-hosted.

Main advantage

It reaches the traces themselves rather than stopping at evaluations, at a lower context cost than smaller connectors.

Main weakness

No infrastructure telemetry, and everything is scoped to a project the agent has to name correctly.

Operational risk

Prompt and dataset writes are on by default, and moving a prompt tag can change production behavior.

Frequently asked questions