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.

Using Power Automate, Copilot Studio, or Power Apps?

Those tools don't speak MCP — Microsoft's Custom Connector platform requires Swagger 2.0 with a distinct path per operation. Phoenix exposes a REST facade that wraps the same MCP tools for those consumers. See the Power Automate connector guide.

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
Claude.ai Connectors	Streamable HTTP	OAuth	Supported	Docs
ChatGPT Apps	SSE	OAuth	Supported	Docs
AWS QuickSuite	Streamable HTTP	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:

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

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

Restart Cursor
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:

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

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

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:

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

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

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:

Open Windsurf Settings
Navigate to MCP Servers section
Add Phoenix:

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

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:

In your n8n workflow, add an "MCP Tool" node
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:

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

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

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

OAuth clients exchange a one-time browser consent for a per-user access token, scoped to that user's Phoenix organization. Three clients are supported today: Claude.ai Connectors, ChatGPT Apps, and AWS QuickSuite. All three drive Dynamic Client Registration (RFC 7591) automatically — no manual client setup is required for the default flows. Each section below is self-contained — pick yours, follow it top to bottom.

If you're integrating a different OAuth-capable client, the Phoenix OAuth endpoints reference and Common 401 causes at the end of this section have everything you need. For full payload-level details, see the OAuth 2.1 Reference.

Claude.ai Connectors

Claude.ai Connectors drive the OAuth flow inside the Claude.ai web UI. Setup is the lightest of the three: Claude handles Dynamic Client Registration (RFC 7591) for you behind the scenes — you don't run any curl commands.

Configuration:

Sign in to Phoenix at phoenix.hginsights.com (Claude needs an active session to complete consent without round-tripping signin).
In Claude.ai, open Settings → Connectors (direct link) and click Add custom connector.
Enter:
- Name: Phoenix
- MCP server URL: https://phoenix.hginsights.com/mcp
Click Add — Claude registers a DCR client, opens the Phoenix consent screen in a popup, and you click Authorize.
Verify by asking Claude: "What Phoenix tools are available?"

Why /mcp and not /api/ai/mcp

Phoenix rewrites /mcp to the canonical OAuth-protected handler at /api/ai/mcp. Same handler either way; the short alias is what Claude.ai's connector form and QuickSuite's wizard expect.

Technical Details:

Transport: Streamable HTTP
Accept Header: application/json, text/event-stream
Authentication: OAuth 2.1 with PKCE
Dynamic Client Registration: handled by Claude.ai
Required scope: mcp:tools (Claude requests this automatically)

ChatGPT Apps

ChatGPT Apps (and Custom GPT Actions) connect via OAuth 2.1 with PKCE. The Apps Directory path runs DCR for you; the Custom GPT path is manual.

Apps Directory submission (automatic DCR)

In your Apps manifest, declare the Phoenix OAuth and MCP endpoints:

Authorization URL: https://phoenix.hginsights.com/oauth/authorize
Token URL: https://phoenix.hginsights.com/oauth/token
Scope: mcp:tools offline_access
MCP server URL: https://phoenix.hginsights.com/api/ai/mcp

ChatGPT performs DCR at app activation time and persists client_id/client_secret in OpenAI's tenant. End users click Connect on the Phoenix listing, sign in to Phoenix (if not already signed in), and approve.

Custom GPT (manual DCR)

If you're embedding Phoenix in a Custom GPT instead of submitting to the Apps Directory, you register the OAuth client yourself.

Register a Phoenix OAuth client. Use your custom GPT's callback URL as the redirect URI (you can find it in the Custom GPT editor when you select OAuth as the auth method).

curl -s -X POST https://phoenix.hginsights.com/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "Phoenix Custom GPT",
    "redirect_uris": ["<your-custom-gpt-callback-url>"],
    "grant_types": ["authorization_code", "refresh_token"],
    "token_endpoint_auth_method": "client_secret_post",
    "scope": "mcp:tools offline_access"
  }' | jq

The response gives you client_id and client_secret. Save both — Phoenix won't show the secret again.

Paste back into the Custom GPT editor. Add an Action with:

GPT editor field	Value
Server URL	`https://phoenix.hginsights.com/api/ai/mcp`
Authentication	OAuth 2.0
Client ID	`client_id` from DCR
Client Secret	`client_secret` from DCR
Authorization URL	`https://phoenix.hginsights.com/oauth/authorize`
Token URL	`https://phoenix.hginsights.com/oauth/token`
Scope	`mcp:tools offline_access`

Save and test. ChatGPT runs the consent flow; the user signs in to Phoenix and approves.

Technical Details:

Transport: Server-Sent Events (SSE)
Accept Header: text/event-stream
Authentication: OAuth 2.1 with PKCE
Dynamic Client Registration: automatic for Apps Directory, manual for Custom GPTs

AWS QuickSuite

AWS QuickSuite (formerly QuickSight) connects to Phoenix using its built-in Dynamic Client Registration support. QuickSuite handles the OAuth client setup automatically — you only paste the Phoenix MCP endpoint and approve the consent screen.

Configuration

Connect step. In QuickSuite, open Connectors → Create for your team → Model Context Protocol. On the Connect step, fill:

QuickSuite field Value
Name Phoenix (or whatever you want to call it)
MCP server endpoint https://phoenix.hginsights.com/mcp
Connection type Public network
Authenticate step. Leave the OAuth Configuration dropdown on Default OAuth app. QuickSuite will display "No additional credentials are needed." — that's the DCR path; QuickSuite registers a per-tenant OAuth client with Phoenix automatically.
Click Create and continue. QuickSuite opens the Phoenix consent flow in a popup. Sign into Phoenix (if not already signed in) and click Authorize.
Verify by running a Phoenix-backed query in QuickSuite — the tool catalog should appear.

QuickSuite field	Value
Name	`Phoenix` (or whatever you want to call it)
MCP server endpoint	`https://phoenix.hginsights.com/mcp`
Connection type	`Public network`

Service authentication is not supported

QuickSuite's "Service authentication" tab uses the OAuth 2.0 client-credentials grant for headless automations. Phoenix only issues tokens against a user identity (org membership is per-user), so use the API-key path for service automations: see the Power Automate connector guide or Authentication.

Troubleshooting

"An internal service error occurred" with an AWS-side RequestId, before the consent popup appears. AWS surfaces this when its validator can't reach or can't parse Phoenix's OAuth discovery metadata. Confirm https://phoenix.hginsights.com/.well-known/oauth-authorization-server returns valid JSON with absolute URLs for authorization_endpoint, token_endpoint, and registration_endpoint, then retry from the Connect step.

Consent popup appears, you click Authorize, then "401 Unauthorized POST .../oauth/token". See Common 401 causes for the full decoder ring against the error_description field.

Technical Details:

Transport: Streamable HTTP (JSON mode)
Accept Header: application/json (not the dual header — QuickSuite is the inverse of ChatGPT here; Phoenix detects QuickSuite's plain-JSON Accept and routes through enableJsonResponse: true mode)
Authentication: OAuth 2.1 with PKCE; Phoenix accepts client_secret via either Basic auth header or request body (RFC 6749 §2.3.1)
Dynamic Client Registration: handled by QuickSuite (RFC 7591); Resource Indicators (RFC 8707) bind tokens to https://phoenix.hginsights.com/mcp

Phoenix OAuth endpoints reference

The values referenced from each client section above, in one place:

Field	Value
Discovery	`https://phoenix.hginsights.com/.well-known/oauth-authorization-server`
Authorization URL	`https://phoenix.hginsights.com/oauth/authorize`
Token URL	`https://phoenix.hginsights.com/oauth/token`
Registration (DCR)	`https://phoenix.hginsights.com/oauth/register`
MCP endpoint (canonical)	`https://phoenix.hginsights.com/api/ai/mcp`
MCP endpoint (short alias, used by Claude.ai and QuickSuite)	`https://phoenix.hginsights.com/mcp`
PKCE	`S256` only

Scopes:

Scope	When to include it
`mcp:tools`	Required for every client. Allows tool execution.
`offline_access`	Optional. Issues a refresh token so users don't re-consent every hour.
`mcp:read`	Read-only data access; rarely useful on its own.

For full payload-level details, see the OAuth 2.1 Reference.

Common 401 causes at `/oauth/token`

Every 401 from /oauth/token returns error: invalid_client. The disambiguator is error_description:

`error_description`	Trigger
`Client not found`	The `client_id` is unknown. Re-run DCR.
`Client credentials required (Basic auth header or client_secret body parameter)`	Confidential client sent neither a Basic auth header nor a body `client_secret`. Include the secret in one of the two transports.
`Invalid client credentials`	Wrong `client_secret` (whether sent via Basic header or in the body).
`Malformed Basic auth header/credentials`	Header isn't `Basic <base64(client_id:client_secret)>` shape.
`Basic auth client_id does not match body client_id`	Header `client_id` and body `client_id` disagree.
`Unsupported token_endpoint_auth_method: …`	The client's registered auth method isn't one of `none`, `client_secret_basic`, `client_secret_post`.

Confidential clients can use either transport

Phoenix accepts the client_secret from either the Authorization: Basic header or the request body for any client registered with client_secret_basic or client_secret_post, per RFC 6749 §2.3.1. The registered method is advisory, not strict — so you don't need to match the auth method you used at registration time. Sending credentials via both channels in a single request is still rejected (with 400 invalid_request).

If your client logs show a 401 with error: invalid_grant, that response is actually a 400 — the authorization code expired (10 min TTL), was reused, or the code_verifier doesn't match the code_challenge.

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:

Break operations into smaller chunks
Use pagination for large data requests
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 the redirect URI registered with DCR exactly matches the one your client sends
Verify the OAuth token hasn't expired (1-hour TTL; use offline_access to refresh)
For 401s on /oauth/token, see Common 401 causes

Supported MCP Clients

Client Compatibility Matrix

API Key Clients

Cursor

Claude Code

Cline

VS Code Copilot

Windsurf

n8n

Claude Desktop

OAuth Clients

Claude.ai Connectors

ChatGPT Apps

Apps Directory submission (automatic DCR)

Custom GPT (manual DCR)

AWS QuickSuite

Configuration

Troubleshooting

Phoenix OAuth endpoints reference

Common 401 causes at `/oauth/token`

Troubleshooting

406 Not Acceptable Error

Connection Timeout

Authentication Errors

Tools Not Appearing

MCP Protocol References

Need Help?

Client Compatibility Matrix​

API Key Clients​

Cursor​

Claude Code​

Cline​

VS Code Copilot​

Windsurf​

n8n​

Claude Desktop​

OAuth Clients​

Claude.ai Connectors​

ChatGPT Apps​

Apps Directory submission (automatic DCR)​

Custom GPT (manual DCR)​

AWS QuickSuite​

Configuration​

Troubleshooting​

Phoenix OAuth endpoints reference​

Common 401 causes at /oauth/token​

Troubleshooting​

406 Not Acceptable Error​

Connection Timeout​

Authentication Errors​

Tools Not Appearing​

MCP Protocol References​

Need Help?​

Client Compatibility Matrix

API Key Clients

Cursor

Claude Code

Cline

VS Code Copilot

Windsurf

n8n

Claude Desktop

OAuth Clients

Claude.ai Connectors

ChatGPT Apps

Apps Directory submission (automatic DCR)

Custom GPT (manual DCR)

AWS QuickSuite

Configuration

Troubleshooting

Phoenix OAuth endpoints reference

Common 401 causes at `/oauth/token`

Troubleshooting

406 Not Acceptable Error

Connection Timeout

Authentication Errors

Tools Not Appearing

MCP Protocol References

Need Help?