Troubleshooting

Common issues with the eGain MCP and how to fix them.

The most common cause: Remote MCP is not enabled in your eGain Administration Console. Enabling it is what registers your tenant with the MCP server — including the details your AI client needs to sign you in. Until then, authentication cannot start.

Fix:

1. In the Administration Console, confirm the Enable Remote MCP toggle is on.
2. Re-copy the MCP Server URL and reconnect in your AI client.

If the MCP page or the Enable Remote MCP toggle isn't in your Administration Console, Contact Support to enable Remote MCP or confirm availability.

Remote MCP was turned off in the Administration Console. Turn the toggle back on and retry.

Tenant not found usually means the MCP Server URL does not match a registered tenant. Check for a typo in the tenant ID, a typo in the MCP hostname, the wrong environment, or extra whitespace when pasting the URL.

If Remote MCP was never enabled for that partition, the tenant is not registered with the MCP server. Turn on Enable Remote MCP, re-copy the MCP Server URL from the Administration Console, and reconnect.

Sessions expire by design. Your AI client may prompt you to sign in again automatically — just complete the sign-in. If it keeps looping, disconnect the connector and reconnect.

Disconnect the connector in your AI client (in Claude: Settings → Connectors → disconnect), then reconnect and sign in again. This is also the fix when switching to a different eGain tenant — reconnect with the new tenant's MCP Server URL.

Your eGain account doesn't have access to that portal or article. The MCP only sees what your account can see. Ask your eGain administrator to check your portal access and your client app's API permissions.

You likely connected with the anonymous MCP URL. Anonymous connections only return publicly available content — even if you signed in. Disconnect and reconnect using the authenticated MCP Server URL.

If authoring tools such as create-article and get-folders don't appear or don't work, check that:

• Authoring early access is enabled for your tenant. To request it, Contact Support.
• You connected with the Agent MCP Server URL. Authenticated Customer and Anonymous Customer connections don't include authoring tools.
• Your eGain user has the Author or Knowledge Base Manager role.

token_exchange_failed means sign-in could not be completed during the OAuth token exchange. Check the error_description shown by your AI client. Retry once after a moment. If it persists, disconnect and reconnect using a freshly copied MCP Server URL.

Persistent failures usually point to a misconfigured client app or an expired authorization code, not a temporary server issue.

Remote MCP server logs are not user-accessible. When contacting support, include:

• The full error code and message shown by your AI client or tool result
• The MCP Server URL you connected with
• What you were trying to do, including the tool and portal if known
• When it happened, including your timezone

Contact Support.

These apply only if you run the open-source MCP server locally. For the full local guide, see the FAQ & Troubleshooting page on GitHub.

• The most common cause is a wrong or missing --api-domain in your MCP configuration file. Find your API Domain in the Administration Console under Partition → Integration → Client Application → Metadata.
• The browser sign-in window times out after 2 minutes for security. If you miss it, retry and complete sign-in promptly.

Any of these works:

• Run the logout script: node scripts/logout.js (removes the saved token and cached files)
• Delete the .bearer_token files manually
• Wait for the token to expire (about 1 hour default) — the next request triggers a fresh sign-in

The local server writes logs through your AI client's MCP integration. Common locations:

• Claude Desktop (macOS): ~/Library/Logs/Claude/mcp*.log
• Claude Desktop (Windows): %APPDATA%\Claude\logs
• Other clients, including Cursor: check your client's MCP or developer documentation for log paths

For more detail, start the server with --log-level debug. See the FAQ & Troubleshooting page on GitHub for client-specific guidance.

Covered in the GitHub FAQ: Node version conflicts with npx, Safari not being supported for sign-in, macOS Automation permissions, and needing to fully restart your AI client after configuration changes.