--- sidebar_position: 2 description: "Setup instructions for connecting Cursor, Claude Code, Cline, Claude Desktop, ChatGPT, AWS QuickSuite, and other MCP clients to HG Insights." --- # 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. :::tip 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](./power-automate-setup.md). ::: ## Client Compatibility Matrix | Client | Transport | Authentication | Status | Documentation | |--------|-----------|----------------|--------|---------------| | [Cursor](#cursor) | Streamable HTTP | API Key | Supported | [Docs](https://docs.cursor.com/context/model-context-protocol) | | [Claude Code](#claude-code) | Streamable HTTP | API Key | Supported | [Docs](https://docs.anthropic.com/en/docs/claude-code/mcp) | | [Cline](#cline) | Streamable HTTP | API Key | Supported | [Docs](https://github.com/cline/cline) | | [VS Code Copilot](#vs-code-copilot) | Streamable HTTP | API Key | Supported | [Docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) | | [Windsurf](#windsurf) | Streamable HTTP | API Key | Supported | [Docs](https://docs.windsurf.com/windsurf/cascade/mcp) | | [n8n](#n8n) | Streamable HTTP | API Key | Supported | [Docs](https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.toolmcp/) | | [Claude Desktop](#claude-desktop) | Streamable HTTP | API Key | Supported | [Docs](https://modelcontextprotocol.io/quickstart/user) | | [Claude.ai Connectors](#claudeai-connectors) | Streamable HTTP | OAuth | Supported | [Docs](#claudeai-connectors) | | [ChatGPT Apps](#chatgpt-apps) | SSE | OAuth | Supported | [Docs](https://platform.openai.com/docs/actions) | | [AWS QuickSuite](#aws-quicksuite) | Streamable HTTP | OAuth | Supported | [Docs](https://docs.aws.amazon.com/quicksuite/) | ## API Key Clients These clients connect directly using your HG Insights API key. ### Cursor [Cursor](https://cursor.com) is an AI-powered code editor with built-in MCP support. **Configuration:** 1. Open Cursor Settings (Cmd/Ctrl + ,) 2. Search for "MCP" 3. Add the HG MCP Server: ```json { "mcpServers": { "hg-mcp-server": { "url": "https://phoenix.hginsights.com/api/ai/YOUR_API_KEY/mcp" } } } ``` 4. Restart Cursor 5. 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](https://docs.anthropic.com/en/docs/claude-code) is Anthropic's official CLI for Claude. **Configuration:** ```bash # 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`: ```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](https://github.com/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 the HG MCP Server: ```json { "cline.mcpServers": { "hg-mcp-server": { "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](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) 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 the HG MCP Server: ```json { "github.copilot.chat.mcpServers": { "hg-mcp-server": { "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](https://windsurf.com) is an AI-powered IDE with MCP support. **Configuration:** 1. Open Windsurf Settings 2. Navigate to MCP Servers section 3. Add the HG MCP Server: ```json { "mcpServers": { "hg-mcp-server": { "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](https://n8n.io) 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](https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.toolmcp/) 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](https://claude.ai/download) 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](https://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 HG MCP Server tools are available?" :::tip mcp-remote fallback If you prefer a local config file approach, you can use [mcp-remote](https://www.npmjs.com/package/mcp-remote) as an alternative: ```json { "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](#claudeai-connectors), [ChatGPT Apps](#chatgpt-apps), and [AWS QuickSuite](#aws-quicksuite). All three drive Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) automatically — no manual client setup is required for the default flows. Each section below is self-contained — pick yours, follow it top to bottom. :::info 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](#hg-insights-oauth-endpoints-reference) and [Common 401 causes](#common-401-causes-at-oauthtoken) at the end of this section have everything you need. For full payload-level details, see the [OAuth 2.1 Reference](/oauth). --- ### 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](https://datatracker.ietf.org/doc/html/rfc7591)) for you behind the scenes — you don't run any curl commands. **Configuration:** 1. Sign in to HG Insights at [phoenix.hginsights.com](https://phoenix.hginsights.com) (Claude needs an active session to complete consent without round-tripping signin). 2. In Claude.ai, open **Settings → Connectors** ([direct link](https://claude.ai/customize/connectors)) and click **Add custom connector**. 3. Enter: - **Name**: `HG MCP Server` (name the connector exactly this) - **MCP server URL**: `https://phoenix.hginsights.com/mcp` 4. Click **Add** — Claude registers a DCR client, opens the HG Insights consent screen in a popup, and you click **Authorize**. 5. Verify by asking Claude: "What HG MCP Server tools are available?" :::note 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. 1. **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). ```bash 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": [""], "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](#common-401-causes-at-oauthtoken) for token-exchange errors once your client is registered. 2. **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` | 3. 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](https://aws.amazon.com/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 1. **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` | 2. **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. 3. 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**. 4. Verify by running an HG Insights-backed query in QuickSuite — the tool catalog should appear. :::tip 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](./power-automate-setup.md) or [Authentication](/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](#common-401-causes-at-oauthtoken) 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](/oauth). --- ### 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 ` 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`. | :::note 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: 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 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](#common-401-causes-at-oauthtoken) ### Tools Not Appearing If HG MCP Server 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 HG MCP Server tools" --- ## MCP Protocol References - [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports) - [MCP Transport Future](https://blog.modelcontextprotocol.io/posts/2025-12-19-mcp-transport-future/) - [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) - Official testing tool --- ## Need Help? - Contact your HG Insights account team for support - [View API documentation](/api) - [Browse example workflows](/examples/company-analysis)