Supported MCP Clients

HG Insights 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. HG Insights 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 HG Insights 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 the HG MCP Server:

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

Restart Cursor
Verify by asking: "What HG MCP Server 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 the HG MCP Server
claude mcp add hg-mcp-server --transport http \
  --url "https://phoenix.hginsights.com/api/ai/YOUR_API_KEY/mcp"

Or add to your .claude/settings.json:

{
  "mcpServers": {
    "hg-mcp-server": {
      "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 the HG MCP Server:

{
  "cline.mcpServers": {
    "hg-mcp-server": {
      "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 the HG MCP Server:

{
  "github.copilot.chat.mcpServers": {
    "hg-mcp-server": {
      "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 the HG MCP Server:

{
  "mcpServers": {
    "hg-mcp-server": {
      "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 HG MCP Server tools are available?"

mcp-remote fallback

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

{
  "mcpServers": {
    "hg-mcp-server": {
      "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 HG Insights 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.

Access tokens expire after 1 hour

HG Insights OAuth access tokens have a 1-hour TTL. Request the offline_access scope during authorization to also receive a refresh token, so your client can silently obtain a new access token instead of prompting the user to re-consent every hour. The supported clients above handle refresh for you; a custom client must implement the refresh-token grant. A 401 with an otherwise-valid token usually just means the hour elapsed — refresh and retry.

If you're integrating a different OAuth-capable client, the HG Insights 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 HG Insights 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: HG MCP Server (name the connector exactly this)
- MCP server URL: https://phoenix.hginsights.com/mcp
Click Add — Claude registers a DCR client, opens the HG Insights consent screen in a popup, and you click Authorize.
Verify by asking Claude: "What HG MCP Server tools are available?"

Why /mcp and not /api/ai/mcp

HG Insights 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 HG Insights 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 HG Insights listing, sign in to HG Insights (if not already signed in), and approve.

Custom GPT (manual DCR)

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

Register an HG Insights 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": "HG MCP Server 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 — HG Insights won't show the secret again.

If registration fails: a non-2xx response usually means a malformed redirect_uris (must be an absolute HTTPS URL matching your Custom GPT's callback exactly) or a missing Content-Type: application/json header. See Common 401 causes for token-exchange errors once your client is registered.

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 HG Insights 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 HG Insights using its built-in Dynamic Client Registration support. QuickSuite handles the OAuth client setup automatically — you only paste the HG MCP Server 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 HG MCP Server (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 HG Insights automatically.
Click Create and continue. QuickSuite opens the HG Insights consent flow in a popup. Sign into HG Insights (if not already signed in) and click Authorize.
Verify by running an HG Insights-backed query in QuickSuite — the tool catalog should appear.

QuickSuite field	Value
Name	`HG MCP Server` (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. HG Insights 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 HG Insights' 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; HG Insights detects QuickSuite's plain-JSON Accept and routes through enableJsonResponse: true mode)
Authentication: OAuth 2.1 with PKCE; HG Insights 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

HG Insights 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

HG Insights 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. HG Insights 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

HG MCP Server 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

Tools Not Appearing

If HG MCP Server tools don't appear in your client:

Restart your MCP client
Check client logs for connection errors
Verify the MCP server URL is correct
Test with a simple tool call: "List HG MCP Server tools"

MCP Protocol References

Need Help?

Contact your HG Insights account team for support
View API documentation
Browse example workflows

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​

HG Insights 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

HG Insights 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?