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

# Troubleshooting

> Solutions for common Civic setup and connection issues

## Primary Client Issues (ChatGPT & Claude)

### 401 Authentication Errors

<AccordionGroup>
  <Accordion title="401 Unauthorized - ChatGPT/Claude Connector" icon="key">
    **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
  </Accordion>

  <Accordion title="401 During Tool Usage" icon="exclamation-triangle">
    **Symptoms:** Connector connects but tools return "Unauthorized" errors

    **Solutions:**

    * Visit [app.civic.com](https://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.)
  </Accordion>
</AccordionGroup>

### 404 Not Found Errors

<AccordionGroup>
  <Accordion title="404 Connector Not Found" icon="link-slash">
    **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](https://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)
  </Accordion>

  <Accordion title="404 During Tool Usage" icon="server">
    **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
  </Accordion>
</AccordionGroup>

### Connection Issues

<AccordionGroup>
  <Accordion title="Connector shows as disconnected" icon="link-slash">
    **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
  </Accordion>

  <Accordion title="Authentication popup blocked" icon="shield">
    **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
  </Accordion>

  <Accordion title="Tools don't appear after connecting" icon="server">
    **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
  </Accordion>
</AccordionGroup>

## Authentication Issues

<AccordionGroup>
  <Accordion title="Repeated login prompts" icon="key">
    **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
  </Accordion>

  <Accordion title="OAuth errors from connected services" icon="exclamation-triangle">
    **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
  </Accordion>

  <Accordion title="403/401 errors" icon="lock">
    **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
  </Accordion>
</AccordionGroup>

## Performance Issues

<AccordionGroup>
  <Accordion title="Slow responses" icon="hourglass">
    **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
  </Accordion>

  <Accordion title="Timeouts" icon="clock">
    **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
  </Accordion>
</AccordionGroup>

## Client-Specific Issues

### Claude Desktop

<AccordionGroup>
  <Accordion title="Connector shows as disconnected" icon="claude">
    **Solutions:**

    * Update Claude Desktop to latest version
    * Remove connector and re-add with fresh MCP URL
    * Check macOS system preferences allow Claude network access
  </Accordion>

  <Accordion title="Tools not working or unavailable" icon="tools">
    **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
  </Accordion>
</AccordionGroup>

### Cursor

<AccordionGroup>
  <Accordion title="MCP features not working after install" icon="cursor">
    **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
  </Accordion>
</AccordionGroup>

### VS Code

<AccordionGroup>
  <Accordion title="MCP extension not loading" icon="code">
    **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
  </Accordion>
</AccordionGroup>

## 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
</Warning>

**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](/civic/organizations) page.

## Getting Help

### Before Contacting Support

Gather this information to speed up resolution:

<Steps>
  <Step title="System Info">
    * Operating system and version
    * Client type and version
  </Step>

  <Step title="Connection Details">
    * What error messages do you see?
    * When did the issue start?
    * Which client are you using?
  </Step>

  <Step title="Recent Changes">
    * Updated any software recently?
    * Changed network or VPN settings?
    * New corporate security policies?
  </Step>
</Steps>

### Contact Support

<Card title="Get Personalized Help" icon="slack" href="https://join.slack.com/t/civic-developers/shared_invite/zt-37tv9fyo7-aDT43mUjOFQwdQFmfZLTRw">
  Include your system info and error details for faster resolution
</Card>

<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.
</Info>

## 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:

```bash theme={null}
# 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:

<Steps>
  <Step title="Clear Client Settings">
    Remove Civic connector from client
  </Step>

  <Step title="Clear Browser Data">
    Clear cookies/data for civic.com and app.civic.com
  </Step>

  <Step title="Restart">
    Restart client and browser
  </Step>

  <Step title="Reconfigure">
    Start setup process from the beginning
  </Step>
</Steps>