Supported MCP Clients

Phoenix supports a variety of MCP (Model Context Protocol) clients. This guide covers setup instructions and compatibility details for each supported client.

Client Compatibility Matrix

Client	Transport	Authentication	Status	Documentation
Cursor	Streamable HTTP	API Key	Supported	Docs
Claude Code	Streamable HTTP	API Key	Supported	Docs
Cline	Streamable HTTP	API Key	Supported	Docs
VS Code Copilot	Streamable HTTP	API Key	Supported	Docs
Windsurf	Streamable HTTP	API Key	Supported	Docs
n8n	Streamable HTTP	API Key	Supported	Docs
Claude Desktop	Streamable HTTP	API Key	Supported	Docs
ChatGPT	SSE	OAuth	Supported	Docs

API Key Clients

These clients connect directly using your Phoenix API key.

Cursor

Cursor is an AI-powered code editor with built-in MCP support.

Configuration:

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Search for "MCP"
3. Add Phoenix as an MCP server:

{
  "mcpServers": {
    "phoenix": {
      "url": "https://phoenix.hginsights.com/api/ai/YOUR_API_KEY/mcp"
    }
  }
}

4. Restart Cursor
5. Verify by asking: "What Phoenix tools are available?"

Technical Details:

• Transport: Streamable HTTP
• Accept Header: application/json
• Authentication: API key in URL path

---

Claude Code

Claude Code is Anthropic's official CLI for Claude.

Configuration:

# Add Phoenix as an MCP server
claude mcp add phoenix --transport http \
  --url "https://phoenix.hginsights.com/api/ai/YOUR_API_KEY/mcp"

Or add to your .claude/settings.json:

{
  "mcpServers": {
    "phoenix": {
      "transport": "http",
      "url": "https://phoenix.hginsights.com/api/ai/YOUR_API_KEY/mcp"
    }
  }
}

Technical Details:

• Transport: Streamable HTTP
• Accept Header: application/json, text/event-stream
• Authentication: API key in URL path

---

Cline

Cline is an AI coding assistant available as a VS Code extension with MCP support.

Configuration:

1. Open VS Code Settings (Cmd/Ctrl + ,)
2. Search for "Cline MCP"
3. Click "Edit in settings.json"
4. Add Phoenix:

{
  "cline.mcpServers": {
    "phoenix": {
      "url": "https://phoenix.hginsights.com/api/ai/YOUR_API_KEY/mcp"
    }
  }
}

5. Reload VS Code

Technical Details:

• Transport: Streamable HTTP
• Accept Header: application/json, text/event-stream
• Authentication: API key in URL path

---

VS Code Copilot

GitHub Copilot in VS Code supports MCP servers for extended capabilities.

Configuration:

1. Open VS Code Settings (Cmd/Ctrl + ,)
2. Search for "Copilot MCP"
3. Click "Edit in settings.json"
4. Add Phoenix:

{
  "github.copilot.chat.mcpServers": {
    "phoenix": {
      "url": "https://phoenix.hginsights.com/api/ai/YOUR_API_KEY/mcp"
    }
  }
}

5. Reload VS Code

Technical Details:

• Transport: Streamable HTTP
• Accept Header: application/json, text/event-stream
• Authentication: API key in URL path

---

Windsurf

Windsurf is an AI-powered IDE with MCP support.

Configuration:

1. Open Windsurf Settings
2. Navigate to MCP Servers section
3. Add Phoenix:

{
  "mcpServers": {
    "phoenix": {
      "url": "https://phoenix.hginsights.com/api/ai/YOUR_API_KEY/mcp"
    }
  }
}

4. Restart Windsurf

Technical Details:

• Transport: Streamable HTTP
• Accept Header: application/json, text/event-stream
• Authentication: API key in URL path

---

n8n

n8n is a workflow automation platform with MCP integration.

Configuration:

1. In your n8n workflow, add an "MCP Tool" node
2. Configure the server connection:
   • Server URL: https://phoenix.hginsights.com/api/ai/YOUR_API_KEY/mcp
   • Transport: HTTP

See the n8n MCP documentation for detailed setup instructions.

Technical Details:

• Transport: Streamable HTTP
• Accept Header: application/json, text/event-stream
• Authentication: API key in URL path

---

Claude Desktop

Claude Desktop supports remote MCP servers natively via the Connectors UI.

Configuration:

1. Open Claude Desktop
2. Navigate to Customize → Connectors (or visit claude.ai/customize/connectors)
3. Add a new connector with the URL:

https://phoenix.hginsights.com/api/ai/YOUR_API_KEY/mcp

4. Save and verify by asking Claude: "What Phoenix tools are available?"

mcp-remote fallback

If you prefer a local config file approach, you can use mcp-remote as an alternative:

{
  "mcpServers": {
    "phoenix": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://phoenix.hginsights.com/api/ai/YOUR_API_KEY/mcp"
      ]
    }
  }
}

This adds latency and requires Node.js — the Connectors UI is the recommended approach.

Technical Details:

• Transport: Streamable HTTP
• Authentication: API key in URL path

---

OAuth Clients

These clients use OAuth 2.1 for authentication. For complete OAuth flow, discovery, and token management details, see the OAuth 2.1 Reference.

ChatGPT (OpenAI Actions)

ChatGPT Actions allow custom GPTs to connect to external services.

Configuration:

1. Create a new Custom GPT or edit an existing one
2. Add an Action with:
   • Server URL: https://phoenix.hginsights.com/api/ai/mcp
   • Authentication: OAuth 2.0
3. Configure OAuth settings:
   • Authorization URL: https://phoenix.hginsights.com/oauth/authorize
   • Token URL: https://phoenix.hginsights.com/oauth/token
   • Scope: mcp:tools offline_access

Technical Details:

• Transport: Server-Sent Events (SSE)
• Accept Header: text/event-stream
• Authentication: OAuth 2.1 with PKCE
• Supports Dynamic Client Registration (DCR)

---

Troubleshooting

406 Not Acceptable Error

If you receive a 406 error, your client may be sending an incompatible Accept header. Phoenix supports:

• application/json
• text/event-stream
• application/json, text/event-stream
• */* (wildcard)

Contact support if your client uses a different Accept header pattern.

Connection Timeout

Phoenix MCP endpoints have a 60-second timeout. For long-running tool calls:

1. Break operations into smaller chunks
2. Use pagination for large data requests
3. Consider using the REST API for batch operations

Authentication Errors

API Key clients:

• Verify your API key is correctly embedded in the URL
• Ensure the key hasn't been revoked
• Check that your organization has MCP access enabled

OAuth clients:

• Complete the OAuth flow in your browser
• Check that redirect URIs are correctly configured
• Verify the OAuth token hasn't expired

Tools Not Appearing

If Phoenix tools don't appear in your client:

1. Restart your MCP client
2. Check client logs for connection errors
3. Verify the MCP server URL is correct
4. Test with a simple tool call: "List Phoenix tools"

---

MCP Protocol References

• MCP Specification
• MCP Transport Future
• MCP Inspector - Official testing tool

---

Need Help?

• Report an issue
• View API documentation
• Browse example workflows