Remote MCP Server

Connect AI assistants directly to your Phoenix instance through the MCP endpoint built into the Phoenix server — no local install required.

Phoenix ships a remote MCP server built directly into the Phoenix server. Point any MCP-compatible client (Claude Code, Cursor, VS Code, and others) at your Phoenix instance’s /mcp endpoint and it can search, query, and operate on your projects, traces, datasets, experiments, prompts, and annotations — everything the Phoenix REST API can do.

The remote MCP server is in beta. We are still tuning the tools and building out agent skills around them, so tool names, behavior, and defaults may change between releases. It ships enabled by default, and you can turn it off or restrict it with environment variables.

Feedback is very welcome — please open a GitHub issue with what worked, what didn’t, and what you’d like the tools to do.

For most workflows, the px CLI is the recommended interface and is the better default for coding agents (e.g., Claude Code, Codex, Cursor), covering fetching traces, debugging failures, inspecting experiments, and managing datasets and prompts. Use the MCP tools below for ad-hoc data access from your IDE. See Coding Agents for setting up both.

Endpoint

The MCP server is available at your Phoenix base URL plus /mcp:

Deployment	URL
Local	http://localhost:6006/mcp
Self-hosted	https://your-phoenix.example.com/mcp

Connect

Clients authenticate with OAuth (authorization code + PKCE). Phoenix acts as its own authorization server and supports dynamic client registration, so there is nothing to pre-configure — add the server, and your client opens a browser window where you log in with your Phoenix account. Tokens are scoped to your user’s permissions.

Claude Code

1. Add the Phoenix MCP server

   claude mcp add --transport http phoenix http://localhost:6006/mcp
   
2. Log in

   Run /mcp inside Claude Code, select phoenix, and complete the browser login.

Claude Desktop

1. Add a custom connector

   Go to Settings → Connectors → Add custom connector and enter:

   • Name: Phoenix
   • URL: http://localhost:6006/mcp
2. Log in

   Claude Desktop opens the browser login the first time you use the connector.

Cursor

1. Add the Phoenix MCP server

   Add to ~/.cursor/mcp.json (or project .cursor/mcp.json):

   {
     "mcpServers": {
       "phoenix": {
         "url": "http://localhost:6006/mcp"
       }
     }
   }
   
2. Log in

   Cursor prompts you to log in via the browser on first use.

VS Code

1. Add the Phoenix MCP server

   Run MCP: Add Server from the Command Palette, or add to .vscode/mcp.json:

   {
     "servers": {
       "phoenix": {
         "type": "http",
         "url": "http://localhost:6006/mcp"
       }
     }
   }
   
2. Log in

   VS Code walks you through the browser login when the server first starts.

Codex (OpenAI)

Codex configures remote MCP servers with an API key. Create a Phoenix API key, export it as PHOENIX_API_KEY, and add to ~/.codex/config.toml:

[mcp_servers.phoenix]
url = "http://localhost:6006/mcp"
bearer_token_env_var = "PHOENIX_API_KEY"

Launch codex and run /mcp to verify the server is connected.

Other clients

Any client that supports streamable HTTP and OAuth works. Configure the URL as <your-phoenix-base-url>/mcp and complete the login prompt on first use. For clients without OAuth support, use an API key instead.

If your Phoenix instance runs without authentication, no login is needed.

Replace http://localhost:6006 with your Phoenix endpoint.

Fallback: API keys

For headless environments (CI, sandboxes) or clients that can’t complete a browser login, pass a Phoenix API key as a Bearer header instead:

claude mcp add --transport http phoenix http://localhost:6006/mcp \
  --header "Authorization: Bearer $PHOENIX_API_KEY"

In JSON-based client configs, set the equivalent header:

{
  "mcpServers": {
    "phoenix": {
      "url": "http://localhost:6006/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

How it works

Instead of exposing dozens of individual tools, the server presents a compact code-mode surface by default — five tools that let the agent discover and compose Phoenix operations:

Tool	Purpose
search	Find available operations by query, ranked by relevance
tags	Browse operations by category (projects, spans, datasets, …)
list_tools	List the full operation catalog
get_schema	Fetch parameter schemas for specific operations before calling them
execute	Run Python that chains operations via call_tool(name, params)

The operation catalog is generated from the Phoenix REST API, so the MCP surface always matches what your Phoenix version can do.

execute runs the agent-written Python inside Monty, Pydantic’s sandboxed Python interpreter — no filesystem, network, or import access, with strict time and memory limits. This lets an agent filter, join, and aggregate results across many API calls in one step instead of shuttling raw JSON through its context window.

Prefer not to run agent-written code on your server? Set PHOENIX_ENABLE_MCP_CODE_MODE=false to remove the execute tool and Monty entirely. The server then exposes the API operations as plain MCP tools, grouped by category, which clients reveal on demand via list_tool_groups and enable_tool_group.

Things to try

Show me the latest traces in my default project and summarize any errors

Which experiments ran on my agent-inputs dataset this week, and how did their scores compare?

Find the slowest LLM spans in my support-agent project and break down where the latency comes from

Pull my rag-pipeline prompt and suggest improvements based on recent trace failures

Configuration

Both variables are set on the Phoenix server before startup:

Environment variable	Default	Effect
PHOENIX_ENABLE_MCP_SERVER	true	Master switch. Set to false to remove the /mcp endpoint entirely.
PHOENIX_ENABLE_MCP_CODE_MODE	true	Set to false to disable code execution (the execute tool and the Monty sandbox) and expose plain, group-gated tools instead.

The browser-login flow is served by Phoenix’s built-in OAuth2 authorization server, which has its own controls — a master switch (PHOENIX_ENABLE_OAUTH2_AUTHORIZATION_SERVER), grant expiry, dynamic client registration modes, redirect-host allowlists, and rate limits. See OAuth2 Authorization Server for the full reference.

Security notes

• Authentication is the same as the rest of Phoenix: OAuth access tokens are audience-scoped to /mcp and cannot be replayed against other endpoints, and API keys carry the permissions of the user who created them.
• Code execution is sandboxed: Monty is an interpreter with no filesystem, network, or import access, capped at 30 seconds, 100 MB of memory, and 50 operation calls per execute block. If your security policy forbids executing agent-written code on the server regardless, set PHOENIX_ENABLE_MCP_CODE_MODE=false.
• Treat query results as data, not instructions. Traces and spans contain whatever your application logged, including untrusted user input. Agents should not follow directives found inside telemetry returned by these tools.

Inspecting the server with MCP Inspector

MCP Inspector is the official tool for exercising an MCP server by hand — list its tools, read their schemas, and call them without wiring up a full client. It’s the fastest way to confirm the Phoenix /mcp endpoint is reachable, that auth works, and that a tool returns what you expect.

1. Launch the Inspector

   npx @modelcontextprotocol/inspector
   

   This starts the Inspector and opens it in your browser. No install step — npx fetches it on demand.

2. Connect to the Phoenix endpoint

   In the Inspector’s left panel:

   • Transport Type: Streamable HTTP
   • URL: http://localhost:6006/mcp (or your deployment’s base URL plus /mcp)

   Click Connect. If authentication is enabled on your Phoenix, the Inspector runs the OAuth browser flow automatically — you approve the same consent page your other clients use, and it stores the resulting token for the session.

3. Explore the tools

   Open the Tools tab and click List Tools. With code mode on (the default) you’ll see the discovery surface — search, tags, list_tools, get_schema, and execute. Select any tool, fill in its parameters, and click Run Tool to see the raw result.

   For example, call search with { "query": "latest traces" } to find the relevant operation, then execute with a Python snippet that chains call_tool(...) calls.

Prefer to pass a token yourself instead of the browser flow — for a headless box or CI — expand Authentication in the connection panel and set a Bearer Token to a Phoenix API key. The Inspector then sends Authorization: Bearer <key> and skips OAuth entirely.

Connecting against the group-gated surface (PHOENIX_ENABLE_MCP_CODE_MODE=false) shows list_tool_groups and enable_tool_group instead of execute. Enable a group first, then re-run List Tools to reveal that group’s operations.

Troubleshooting

404 at /mcp: Your Phoenix version predates the MCP server, or it was disabled with PHOENIX_ENABLE_MCP_SERVER=false. Upgrade or re-enable it, or fall back to the npm package.

Login loops or 401 errors: Re-run the login (/mcp in Claude Code, or remove and re-add the server). If you’re using the API-key fallback, confirm the key is valid and passed as Authorization: Bearer <key>.

Server not appearing in your client: Restart the client and verify the config file syntax — most clients only reload MCP config on startup.

Relationship to @arizeai/phoenix-mcp

The @arizeai/phoenix-mcp npm package is a standalone stdio MCP server you run locally via npx. It is now in maintenance mode: it continues to receive bug fixes, but new capabilities land here, in the remote server. Use the remote server whenever your Phoenix version serves the /mcp endpoint, and the npm package only with older Phoenix versions.

Related

Coding Agents

Set up the CLI, MCP, and skills together for a full coding-agent workflow.

API Keys

Create an API key for headless MCP clients.