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

# Troubleshooting

> Common issues and how to fix them when using the Enrichley MCP server.

If something isn't working, start with the quick diagnostic below. Most issues fall into one of four categories: connection, authentication, client-specific, or tool errors.

## Quick diagnostic

Ask your AI assistant:

> *"Check my Enrichley credit balance."*

This calls `enrichley_get_account_status`, which is free and read-only.

* **Returns your credits:** the connection and authentication are healthy. If a different tool isn't working, it's likely a tool-specific issue.
* **Returns an authentication error:** see [Authentication errors](#authentication-errors) below.
* **Hangs or returns a connection error:** see [Connection issues](#connection-issues) below.

## Connection issues

<AccordionGroup>
  <Accordion title="The MCP server is unreachable">
    Confirm the URL is exactly `https://mcp.enrichley.io/mcp`. Trailing slashes, missing `/mcp`, or substituting the base URL will all fail.

    Test the health endpoint in a browser or with curl:

    ```sh theme={null}
    curl https://mcp.enrichley.io/health
    ```

    A healthy server returns `{ "ok": true, "service": "enrichley-mcp-worker" }`.
  </Accordion>

  <Accordion title="The browser sign-in window doesn't open">
    Some clients suppress popups. Look for a clickable link in the client's terminal or status bar that you can open manually. If you have a popup blocker, disable it for the client and retry.
  </Accordion>

  <Accordion title="The browser opens but immediately shows an error">
    The redirect URL your client is using may not match what the server expects. Reset the client's MCP configuration, remove and re-add the Enrichley server, and try again.
  </Accordion>
</AccordionGroup>

## Authentication errors

<AccordionGroup>
  <Accordion title="Account not eligible">
    The signed-in account does not have an active Enrichley plan or a ready API credential. Sign in with the right account or upgrade your plan, then reconnect the client.
  </Accordion>

  <Accordion title="Credential not ready">
    The account API credential is missing, disabled, or temporarily unavailable. Open your Enrichley profile to confirm the account is ready, then reconnect the client.
  </Accordion>

  <Accordion title="Session expired">
    Your AI client's OAuth token has expired. Reconnect to refresh it.

    * **Claude Code:** run `/mcp`, clear authentication for `enrichley`, then reconnect.
    * **Cursor:** disable and re-enable the Enrichley MCP server.
  </Accordion>

  <Accordion title="Unauthorized on every tool call">
    The client is sending requests without a valid token. Run the setup flow again from scratch for that client.
  </Accordion>
</AccordionGroup>

## Client-specific issues

<AccordionGroup>
  <Accordion title="Claude Code: server doesn't appear after install">
    Run `claude mcp list` to confirm `enrichley` is registered. If it isn't, re-run the install command from [Setup](/mcp/setup). After install, run `/mcp` to start the OAuth flow — the server only becomes usable once you complete sign-in.
  </Accordion>

  <Accordion title="Cursor: tools don't show up in chat">
    Restart Cursor after editing `mcp.json`. Open the MCP/tools panel and confirm the Enrichley server is enabled. If it's enabled but tools are missing, complete the OAuth browser flow when Cursor prompts you.
  </Accordion>

  <Accordion title="VS Code: server doesn't appear in MCP: List Servers">
    Make sure your config uses `"servers"` (not `"mcpServers"`) and includes `"type": "http"`. After saving, run **MCP: List Servers** from the command palette and select `enrichley` to start the OAuth flow.
  </Accordion>

  <Accordion title="Codex: codex mcp list shows the server but tools fail">
    The server is registered but you haven't completed OAuth yet. Run `codex mcp login enrichley` and complete the browser sign-in.
  </Accordion>
</AccordionGroup>

## Tool errors

<AccordionGroup>
  <Accordion title="Invalid email format">
    The `enrichley_validate_email` tool requires a syntactically valid email. If your AI assistant pulled an address from text, double-check it for typos or missing characters.
  </Accordion>

  <Accordion title="Rate limit exceeded">
    You've hit the 10 requests/second limit. Wait until `rateLimitResetAt` (returned in the previous tool's `usage` envelope) and retry. For higher throughput, contact [support@enrichley.io](mailto:support@enrichley.io).
  </Accordion>

  <Accordion title="Out of credits">
    The validation tool consumes one credit per call. [Top up or upgrade your plan](https://app.enrichley.io/plans) to keep validating.
  </Accordion>

  <Accordion title="Result was unknown">
    `result: "unknown"` means the upstream provider could not determine the address's status — usually because the receiving server didn't respond. Treat the address as not-safe-to-send and retry later if needed.
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Does the MCP server support SSE transport?">
    No. Streamable HTTP only.
  </Accordion>

  <Accordion title="Does my AI client see my Enrichley API key?">
    No. The key is stored encrypted on the server. Your AI client only ever holds a short-lived OAuth token.
  </Accordion>

  <Accordion title="How do I revoke access for a specific client?">
    The fastest way is to disconnect inside the client itself (`/mcp` in Claude Code, the MCP panel in Cursor). To revoke access for every client at once, rotate your API key on your [Enrichley profile](https://app.enrichley.io/profile).
  </Accordion>

  <Accordion title="Can I use this with ChatGPT?">
    The Enrichley MCP server implements OAuth 2.1 with PKCE, which is what ChatGPT's developer-mode MCP support requires. We haven't validated the integration end-to-end yet, so we're not publishing official setup steps until we do. If you try it and it works, let us know at [support@enrichley.io](mailto:support@enrichley.io).
  </Accordion>

  <Accordion title="Can I run the MCP server locally?">
    No self-hosted version is available. The hosted server at `https://mcp.enrichley.io/mcp` is the only supported deployment.
  </Accordion>
</AccordionGroup>

## Debugging with MCP Inspector

[MCP Inspector](https://modelcontextprotocol.io/legacy/tools/inspector) is the official open-source debugging tool from the Model Context Protocol team. Use it to test the Enrichley server outside of an AI client — it's especially helpful when you want to confirm whether an issue is on the server or on your client's MCP integration.

### Start the inspector

```sh theme={null}
npx @modelcontextprotocol/inspector
```

This starts a local UI in your browser.

### Connect to Enrichley

In the inspector UI, configure:

* **Transport:** `Streamable HTTP`
* **Connection type:** `Via Proxy`
* **URL:** `https://mcp.enrichley.io/mcp`
* **Scope:** `account.read validation.run`
* **Custom Authorization header:** disabled

Click **Connect**, complete the browser sign-in, and authorize the requested scopes. The inspector will list the two tools and let you call them interactively.

### Common inspector gotchas

<AccordionGroup>
  <Accordion title="Connection fails immediately">
    Confirm the transport is set to `Streamable HTTP` (not SSE) and the URL ends with `/mcp`. Some inspector versions default to other transports or other paths.
  </Accordion>

  <Accordion title="Browser sign-in window doesn't open">
    The inspector relies on your default browser handling the OAuth redirect. If you have multiple browsers installed, set your preferred one as the system default before retrying.
  </Accordion>

  <Accordion title="Tools don't appear after connecting">
    Refresh the inspector's tool list by reconnecting. If they still don't show, check the inspector's network tab for a 401 response — that points to an authorization issue, not a tool issue.
  </Accordion>
</AccordionGroup>

## Still need help?

<CardGroup cols={2}>
  <Card title="Email support" icon="envelope" href="mailto:support@enrichley.io">
    Contact our team for account or billing issues.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Full REST API documentation with an interactive playground.
  </Card>
</CardGroup>