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. 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, but Claude.ai's connector form expects the shorter path.

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 via its Custom user based OAuth authentication mode. Unlike Claude.ai and ChatGPT, QuickSuite does not run DCR for you — you register a Phoenix OAuth client up front and paste the credentials into the QuickSuite UI.

Configuration

Connect step. In QuickSuite, start the Phoenix integration setup. On the Connect step, fill:

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

Use the canonical /api/ai/mcp path, not the /mcp alias. The alias is for Claude.ai's connector form; QuickSuite is sensitive to the exact path it was configured with at MCP-call time.
Authenticate step → choose Custom user based OAuth. On the Authenticate step, the dropdown defaults to "Default OAuth app" — that's an AWS-managed OAuth client for services AWS already integrates with, not Phoenix. Switch the OAuth Configuration dropdown to Custom user based OAuth before continuing.
Note QuickSuite's Redirect URL. Once Custom user based OAuth is selected, the form reveals a greyed-out Redirect URL field at the bottom. The canonical AWS pattern is:
```
https://<region>.quicksight.aws.amazon.com/sn/oauthcallback
```
For example, https://us-east-1.quicksight.aws.amazon.com/sn/oauthcallback. Copy whatever QuickSuite is showing you verbatim — different regions and QuickSuite versions surface different hosts, and the value you paste into DCR must match byte-for-byte.
Register a Phoenix OAuth client with that redirect URL:
```
curl -s -X POST https://phoenix.hginsights.com/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "AWS QuickSuite",
    "redirect_uris": ["https://us-east-1.quicksight.aws.amazon.com/sn/oauthcallback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "token_endpoint_auth_method": "client_secret_post",
    "scope": "mcp:tools offline_access"
  }' | jq
```
Replace the redirect URI with whatever QuickSuite showed you. Use "token_endpoint_auth_method": "client_secret_post" — QuickSuite sends client_id and client_secret in the request body at token-exchange time, not as an Authorization: Basic ... header. Registering with client_secret_basic will work through consent but fail at token exchange with error_description: Missing Basic auth header.

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

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

Paste back into QuickSuite. Fill the form fields with:

QuickSuite field	Value
Client ID	`client_id` from DCR (e.g., `phx_client_24df0f…`)
Client secret	`client_secret` from DCR
Token URL	`https://phoenix.hginsights.com/oauth/token`
Authorization URL	`https://phoenix.hginsights.com/oauth/authorize`
Redirect URL	(auto-filled by QuickSuite — must match the URL you passed to DCR in step 4, byte-for-byte)

AWS form validation drops pasted values silently

QuickSuite's form sometimes drops pasted values if you Save before clicking out of the field. If AWS responds with 4 validation errors detected: …authorizationEndpoint failed to satisfy constraint: Member must have length greater than or equal to 1, the URL fields submitted as empty strings. Tab or click out of each field after pasting, confirm the value is still showing, then Save.

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.

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. This is AWS's own validator rejecting the OAuth config you submitted, not a Phoenix error. Common causes:

The discovery doc at /.well-known/oauth-authorization-server is returning malformed URLs (e.g., literal ${VERCEL_BRANCH_URL} placeholders on a misconfigured preview environment). Curl the doc and confirm the authorization_endpoint and token_endpoint are real URLs.
One of the URL fields submitted as empty (see the AWS form-validation gotcha in step 5).
The OAuth Configuration dropdown is still set to "Default OAuth app" (step 2).

Consent popup appears, you click Authorize, then "401 Unauthorized POST .../oauth/token". Phoenix is rejecting QuickSuite's token-exchange request. Almost always one of:

Client was registered with client_secret_basic instead of client_secret_post. QuickSuite uses client_secret_post. Re-register the client with the right method (step 4).
Client secret was copy-pasted with a hidden character or trailing whitespace. Re-register and paste the new secret carefully.
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, client_secret_post (verified empirically; not client_secret_basic)
Dynamic Client Registration: manual (you run it; paste credentials into QuickSuite)

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 (alias for Claude.ai)	`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.
`Missing client_secret`	Used `client_secret_post` but didn't include `client_secret` in the body.
`Invalid client credentials`	Wrong `client_secret` (Basic or post form).
`Missing Basic auth header`	Used `client_secret_basic` but didn't send the `Authorization: Basic …` header.
`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: …`	Auth method isn't one of `none`, `client_secret_basic`, `client_secret_post`.

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?