Skip to main content

Troubleshooting

Primary Client Issues (ChatGPT & Claude)​

401 Authentication Errors​

401 Unauthorized - ChatGPT/Claude Connector

Symptoms: "Unauthorized", "Authentication failed", or "Invalid credentials" when adding MCP connector

For Claude Desktop/Claude.ai:

  • Ensure you have Claude Pro, Team, or Enterprise (MCP not available on free plan)
  • Check that you're signed into your Claude account
  • Remove and re-add the Civic connector with fresh URL
  • Clear browser cache and cookies for claude.ai
  • Verify the MCP URL is correct: https://app.civic.com/hub/mcp

For ChatGPT (when available):

  • Ensure you have ChatGPT Plus or Enterprise
  • Check that MCP connectors are enabled in your subscription
  • Clear browser cache for chatgpt.com
  • Try incognito/private browsing mode
401 During Tool Usage

Symptoms: Connector connects but tools return "Unauthorized" errors

Solutions:

  • Visit app.civic.com and ensure you've authorized the specific services (GitHub, Slack, etc.)
  • Check that your service accounts haven't revoked access
  • Re-authorize individual services: ask your AI "Connect me to GitHub"
  • Verify you have the required permissions (repo access, workspace membership, etc.)

404 Not Found Errors​

404 Connector Not Found

Symptoms: "Connector not found", "Invalid URL", or "Service unavailable" when adding connector

Solutions:

  • Double-check the MCP URL is exactly: https://app.civic.com/hub/mcp
  • Ensure you have created an account at app.civic.com
  • Check your internet connection and try again
  • Corporate firewall may be blocking - try from personal network
  • Wait a few minutes and retry (temporary service issues)
404 During Tool Usage

Symptoms: Connector works but specific tools return "Not Found" errors

Solutions:

  • Check that you selected the required MCP servers at app.civic.com
  • Some tools require specific service permissions - re-authorize the service
  • Try asking: "What MCP servers are available?" to see current connections
  • Service may be temporarily unavailable - try again later

Connection Issues​

Connector shows as disconnected

Symptoms: Civic connector shows "Disconnected" or "Failed" status

Solutions:

  • Check internet connection and try refreshing
  • Remove and re-add the connector with the correct URL
  • Ensure no VPN or proxy is interfering
  • For Claude Desktop: update to latest version
  • For Claude.ai: try refreshing the browser page
Authentication popup blocked

Symptoms: Client tries to connect but no auth window appears

Solutions:

  • Allow popups for your client (Claude Desktop/ChatGPT)
  • Try connecting from a different network (corporate firewalls may block)
  • Clear client cache/settings and re-add the connector
  • Use incognito/private browsing mode for web clients
Tools don't appear after connecting

Symptoms: Connection succeeds but no MCP tools are visible

Solutions:

  • Restart your client completely after initial setup
  • Check app.civic.com - make sure you selected MCP servers
  • Ask your AI: "What MCP tools are available?" to verify connection
  • Complete OAuth flows for each service you want to use

Authentication Issues​

Repeated login prompts

Symptoms: Keep getting asked to sign in despite successful authentication

Solutions:

  • Check system clock is accurate (OAuth tokens are time-sensitive)
  • Clear browser cookies for civic.com and app.civic.com
  • Remove and re-add the connector in your client
OAuth errors from connected services

Symptoms: "Invalid scope", "Access denied", or "Token expired" for GitHub/Slack/etc.

Solutions:

  • Revisit app.civic.com and re-authorize the specific service
  • Check service account permissions (e.g., GitHub org access, Slack workspace admin)
  • Some services require re-authorization after permission changes
  • Token may have been revoked - re-authorize to generate new one
403/401 errors

Symptoms: "Unauthorized" or "Forbidden" errors when using MCP commands

Solutions:

  • Service tokens may have expired - re-authorize at app.civic.com
  • Check rate limits - wait a few minutes and try again
  • Verify you have required permissions (repo access, channel membership, etc.)
  • Contact admin if using workspace/organization accounts

Performance Issues​

Slow responses

Symptoms: MCP commands take a long time to complete

Solutions:

  • First request to each service is slower (authentication)
  • Large operations (file uploads, bulk queries) are inherently slow
  • Check network connection - corporate proxies can add latency
Timeouts

Symptoms: Commands fail with timeout errors

Solutions:

  • Break large requests into smaller chunks
  • Some services have strict rate limits (GitHub API: 5,000/hour)
  • Try the same command later - may be temporary service issues

Client-Specific Issues​

Claude Desktop​

Connector shows as disconnected

Solutions:

  • Update Claude Desktop to latest version
  • Remove connector and re-add with fresh MCP URL
  • Check macOS system preferences allow Claude network access
Tools not working or unavailable

Symptoms: Claude shows connected but can't access your tools, or tools are missing

Solutions:

  1. Check connector status: In Claude Desktop settings, verify Civic connector shows "Connected"
  2. Verify tool access: Ask Claude "What MCP tools are available?" to see current tools
  3. Reauthorize if needed: If tools are missing:
    • Go to Claude Desktop → Settings → Connectors
    • Find Civic connector and click on it
    • If prompted to "Connect" or "Authorize", click it to reauthorize
    • Complete any OAuth flows that appear
  4. Restart Claude: Close and reopen Claude Desktop after reauthorization
  5. Test again: Try using a simple tool command to verify access

Cursor​

MCP features not working after install

Solutions:

  • Restart Cursor completely (not just reload window)
  • Check Cursor Settings → Features → MCP is enabled
  • Try disabling and re-enabling Civic in MCP settings
  • Update Cursor to latest version

VS Code​

MCP extension not loading

Solutions:

  • Install or update the MCP extension from VS Code marketplace
  • Check VS Code settings: search "MCP" and enable required features
  • Reload VS Code window after MCP configuration changes
  • Verify extension has proper permissions

Corporate Network Issues​

Many issues stem from corporate security policies:

warning

Common corporate restrictions that affect Civic:

  • Proxy servers intercepting HTTPS requests
  • TLS certificate inspection causing SSL errors
  • OAuth redirect URLs blocked by content filters

Solutions:

  • Work with IT to whitelist *.civic.com
  • Try initial setup from personal network, then switch to corporate
  • Request proxy bypass for MCP connectors
  • Use company VPN if external setup works

Account Management​

For information on managing organizations, inviting members, switching between organizations, or converting a personal account to an organization, see the Managing Your Organizations page.

Getting Help​

Before Contacting Support​

Gather this information to speed up resolution:

  1. 1
    System Info
    • Operating system and version
    • Client type and version
  2. 2
    Connection Details
    • What error messages do you see?
    • When did the issue start?
    • Which client are you using?
  3. 3
    Recent Changes
    • Updated any software recently?
    • Changed network or VPN settings?
    • New corporate security policies?

Contact Support​

Get Personalized Help

Include your system info and error details for faster resolution
info

Join our Slack community for the latest updates, improvements, and real-time help from other users. We regularly share troubleshooting tips and new features there.

Advanced Debugging​

Enable Debug Logging​

Check your client's documentation for MCP debug/verbose logging options. Most clients support enabling verbose or debug mode for MCP connections.

Network Debugging​

Test connectivity to Civic services:

# Test basic connectivity
curl -I https://app.civic.com

# Test MCP endpoint (should return 405 Method Not Allowed - that's correct)
curl -I https://app.civic.com/hub/mcp

Reset Everything​

If nothing else works, complete reset:

  1. 1
    Clear Client Settings

    Remove Civic connector from client

  2. 2
    Clear Browser Data

    Clear cookies/data for civic.com and app.civic.com

  3. 3
    Restart

    Restart client and browser

  4. 4
    Reconfigure

    Start setup process from the beginning