> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Troubleshooting

> Troubleshooting common issues with the Gumnut MCP server

## Connection Issues

**Problem**: MCP client can't connect

* Verify the server URL is exactly `https://api.gumnut.ai/mcp`
* Check your internet connection
* Ensure your API key is valid
* Try the health endpoint: `curl https://api.gumnut.ai/health`

## Authentication Errors

**Problem**: 401 Unauthorized responses

* Verify API key format: `Bearer apikey_...`
* Check the key hasn't been revoked
* Ensure proper Authorization header
* Try regenerating your API key in the [dashboard](https://app.gumnut.ai)

## ChatGPT: "There was a problem connecting"

**Problem**: Adding the Gumnut connector in ChatGPT fails with **"There was a problem connecting Gumnut Photos. Try again later."** and the sign-in popup closes immediately.

This happens because ChatGPT's connector is registered without the `openid` scope, but with OIDC enabled it still requests `openid` during sign-in. Gumnut's authorization server rejects the request for a scope the connector didn't register, so the connection fails. To fix it:

* Edit the connector (or recreate it) and open **Advanced settings**.
* Under **OpenID support**, uncheck **OIDC enabled**.
* Under **Default scopes**, make sure `openid` is not selected (`profile`, `email`, and `offline_access` are fine).
* Retry the connection.

See [MCP Setup → ChatGPT](/guides/mcp/setup#chatgpt) for the full walkthrough.

## Rate Limiting

**Problem**: 429 Too Many Requests

* Check the `retry-after` header
* Implement exponential backoff
* Consider request batching
* Monitor your usage in the [dashboard](https://app.gumnut.ai)

## CORS Issues

**Problem**: Browser-based client CORS errors

* Ensure using HTTPS
* Check browser console for details
* Verify client sends proper headers
* Contact support if the issue persists

## Tool Not Appearing

**Problem**: Gumnut tools don't show up in your AI assistant

* Restart your AI tool after configuration
* Check configuration file syntax (valid JSON)
* Verify the server name matches in your config
* In Claude Code, run `claude mcp list` to verify registration
* In Cursor, check **Settings > MCP** and click refresh

## Support

Need help with the MCP server?

* **Setup Guide**: [MCP Setup](/guides/mcp/setup)
* **Support**: [www.gumnut.ai/support](https://www.gumnut.ai/support)
* **API Reference**: Full API documentation in the API Reference tab