Troubleshooting

AI assistant doesn’t use the tools

Symptoms: Your AI assistant responds to snippet requests without using the MCP tools.

Solutions:

1. Restart your AI client after adding server configuration
2. Check the configuration file path is correct for your OS
3. Verify the binary path in your configuration exists and is executable
4. Look for errors in your client’s MCP server logs

Test the server directly:

/usr/local/bin/snippets-mcp
# Should output MCP initialization JSON

GitHub Token Errors

“github token not found”

Symptoms: Server fails to start or returns token error.

Solutions:

1. Store token in keychain:

   snippets-mcp --set-credential
   

2. Or set environment variable:

   export GITHUB_TOKEN=ghp_your_token_here
   

3. Verify token is stored:

   • Open Keychain Access.app
   • Search for “snippets-mcp”

“github token is invalid or expired”

Symptoms: Authentication fails when calling tools.

Solutions:

1. Check token status at github.com/settings/tokens
2. Verify token hasn’t expired
3. Re-run snippets-mcp --set-credential with a fresh token

“github token is missing required ‘gist’ scope”

Symptoms: Token validates but operations fail.

Solution: Create a new token with the gist scope enabled:

1. Go to github.com/settings/tokens/new
2. Select gist scope
3. Generate and store the new token

Connection Errors

“Timeout” or “connection refused”

Symptoms: Tools fail with network errors.

Solutions:

1. Check internet connectivity
2. Verify GitHub API is reachable:

   curl https://api.github.com/zen
   

3. Increase timeout for slow connections:

   "env": {
     "SNIPPETS_TIMEOUT": "60s"
   }
   

4. Check if firewall or proxy is blocking api.github.com

Rate limiting

Symptoms: Operations fail after many requests.

Solution: GitHub API has rate limits. Wait a few minutes and retry. Authenticated requests (with valid token) have higher limits than unauthenticated.

No Results

list_snippets returns empty

Possible causes:

1. No gists exist for this GitHub account
2. Filters are too restrictive
3. Token belongs to different account

Solutions:

1. Verify gists exist at gist.github.com
2. Try without filters first
3. Check token belongs to the expected account:

   curl -H "Authorization: token ghp_..." https://api.github.com/user
   

Search doesn’t find expected snippets

Possible causes:

1. Search term not in description
2. Tag format incorrect

Solutions:

1. Search is case-insensitive but matches description text
2. Tags must be hashtags in description (e.g., #go not just go)

Debug Logging

Enable debug logging to see detailed operations:

{
  "mcpServers": {
    "snippets": {
      "command": "/usr/local/bin/snippets-mcp",
      "env": {
        "SNIPPETS_LOG_LEVEL": "debug"
      }
    }
  }
}

Check logs for:

• Token resolution (keychain vs environment)
• API requests and responses
• Error details

Common Error Messages

Keychain Issues

Can’t store token in keychain

macOS: Keychain Access must be unlocked. Check for prompts asking to allow access.

Linux: Requires libsecret and a running secret service (GNOME Keyring or similar).

Windows: Uses Windows Credential Manager.

Token stored but not found

Solutions:

1. Verify service name is “snippets-mcp” in Keychain Access
2. Delete and re-add: snippets-mcp --set-credential
3. Fall back to environment variable if keychain issues persist

Getting Help

If you’re still having issues:

1. Check GitHub Issues for similar problems
2. Open a new issue with:
   • Operating system and version
   • Full error message
   • Steps to reproduce
   • Configuration (with token redacted)