Skip to main content

MCP Server Troubleshooting & FAQ

Common questions and resolution steps when connecting AI agents to the GroupTrack MCP Server.

1. Connection Timeout or Hangs during Handshake​

  • Cause: Certain corporate networks, VPNs, or proxy extensions buffer streaming responses, which delays the initial Server-Sent Events (SSE) handshake event.
  • Solution:
    • Ensure your network environment permits long-lived streaming HTTPS connections to mcp.grouptrackcrm.com.
    • If using a web-based AI assistant, check that browser privacy extensions or VPNs aren't intercepting or buffering event streams.

2. 401 Unauthorized / Repeated Credential Prompts​

  • Cause: Invalid or missing API key, or confusing your Account ID / Team ID with the API Key.
  • Solution:
    1. Open https://app.grouptrackcrm.com/profile/team.
    2. Locate the dedicated API Key section and copy your active key.
    3. Verify the authorization format:
      • Header: Authorization: Bearer <YOUR_API_KEY> or x-api-key: <YOUR_API_KEY>
      • URL Query: https://mcp.grouptrackcrm.com/sse?api-key=<YOUR_API_KEY>

3. Session Expired (404 on /message)​

  • Cause: The client posted to /message?sessionId=... after the SSE stream was closed or timed out due to client inactivity.
  • Solution: Reconnect to /sse to receive a fresh sessionId. Most AI clients (such as Meta Muse and Claude Desktop) automatically reconnect and renew sessions.

4. Semantic Search Returns No Results​

  • Cause: Passing specific person names, tags, or stages into semanticQuery.
  • Solution:
    • For person names: Use the name, firstName, or lastName parameters.
    • For tags: Use the tagName parameter.
    • For pipelines: Use the pipelineName or stageName parameters.
    • semanticQuery is designed for natural language semantic questions across notes and conversation histories (e.g., "leads interested in high-ticket mastermind").

5. Checking Service Availability​

To verify that the hosted MCP server is operational from your terminal:

curl -i https://mcp.grouptrackcrm.com/health

A normal response will return HTTP 200:

{
  "status": "ok",
  "activeSessions": 1,
  "uptime": 12450.5
}