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

# Troubleshooting

> Common issues and solutions for the LeadMagic MCP server

Common issues and solutions for the LeadMagic MCP server.

## Quick Diagnostics

Ask your AI assistant: *"Check my LeadMagic credit balance."*

* **Works?** Your connection and authentication are fine.
* **Doesn't work?** Follow the troubleshooting steps below.

## Connection Issues

<AccordionGroup>
  <Accordion title="Server not found or tools not appearing" icon="plug">
    **Symptoms:** AI assistant doesn't recognize LeadMagic tools, "no tools available," or server appears disconnected.

    **Solutions:**

    1. **Verify the URL** — ensure your config uses exactly `https://mcp.leadmagic.io/mcp` (note the `/mcp` path).
    2. **Restart your client** — most MCP clients require a restart after config changes:
       * **Cursor:** Restart the application
       * **VS Code:** Run `Developer: Reload Window`
       * **Claude Desktop:** Fully quit and reopen
       * **Windsurf:** Restart the application
    3. **Check JSON syntax** — a missing comma or bracket in your config file will silently fail. Validate your JSON at [jsonlint.com](https://jsonlint.com).
    4. **Check the config file location** — make sure you're editing the right file for your client (see [setup guide](/docs/mcp/setup)).
  </Accordion>

  <Accordion title="Connection timeout or slow responses" icon="clock">
    **Symptoms:** Tools take a long time to respond or time out entirely.

    **Solutions:**

    1. **Check your internet connection** — the MCP server runs at `mcp.leadmagic.io` and requires internet access.
    2. **Try the health endpoint** — run this in your terminal to verify the server is reachable:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl https://mcp.leadmagic.io/health
    ```

    You should see `{"ok":true,"service":"lm-mcp",...}`.

    3. **Rate limits** — the LeadMagic API has rate limits. If you're making many rapid requests, you may be temporarily throttled.
  </Accordion>
</AccordionGroup>

## Authentication Errors

<AccordionGroup>
  <Accordion title="401 Unauthorized" icon="lock">
    **Cause:** Missing, expired, or revoked OAuth bearer token.

    **Solutions:**

    1. **Reconnect the server** — remove and re-add the MCP server in your AI client.
    2. **Complete OAuth sign-in** — sign in when the client opens the LeadMagic authorization flow.
    3. **Check the server URL** — use `https://mcp.leadmagic.io/mcp` for most clients and `https://mcp.leadmagic.io` for Claude remote connectors.
    4. **Retry after refresh** — some clients need a restart after completing OAuth.
  </Accordion>

  <Accordion title="403 Forbidden — No credits" icon="coins">
    **Cause:** Your account has no remaining credits.

    **Solutions:**

    1. Check your balance at [app.leadmagic.io](https://app.leadmagic.io).
    2. [Purchase credits](https://app.leadmagic.io/settings/billing) or set up auto top-up.
    3. See [Credits & Pricing](/docs/v1/credits) for plan options.
  </Accordion>
</AccordionGroup>

## Client-Specific Issues

<Tabs>
  <Tab title="Cursor">
    ### Cursor

    **Config not picked up:**

    * Ensure the file is at `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global).
    * Restart Cursor after any config change.

    **Multiple configs:**

    * Project-level config (`.cursor/mcp.json`) takes priority over global (`~/.cursor/mcp.json`).
    * If you have both, the project-level config wins.
  </Tab>

  <Tab title="VS Code">
    ### VS Code

    **Config not picked up:**

    * Ensure the file is at `.vscode/mcp.json` in your workspace root.
    * Run `Developer: Reload Window` after changes.

    **Input variable prompt not appearing:**

    * Make sure the `inputs` array is at the top level of your `mcp.json`, not nested inside `servers`.
    * The prompt appears when the MCP server first connects in a session.
  </Tab>

  <Tab title="Claude Desktop">
    ### Claude Desktop

    **`mcp-remote` not found:**

    * Ensure Node.js 18+ is installed (`node --version`).
    * `npx` should be available in your PATH. Try running `npx mcp-remote --help` in your terminal.

    **Server keeps disconnecting:**

    * `mcp-remote` spawns a local process per session. If Claude Desktop crashes or is force-quit, the process may linger. Check for orphaned `mcp-remote` processes.
    * Update `mcp-remote` to the latest version: `npx mcp-remote@latest`.

    **Config file location:**

    * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
    * **Linux:** `~/.config/Claude/claude_desktop_config.json`
  </Tab>

  <Tab title="Claude Code">
    ### Claude Code

    **Server not appearing:**

    * Run `claude mcp list` to see registered servers.
    * If `leadmagic` is not listed, re-run the add command (see [setup guide](/docs/mcp/setup)).

    **Wrong scope:**

    * `--scope local` (default) only applies to the current project directory.
    * Use `--scope user` to make LeadMagic available everywhere.
  </Tab>

  <Tab title="Windsurf">
    ### Windsurf

    **Config not picked up:**

    * The config file location may vary by Windsurf version. Try both `~/.codeium/mcp_config.json` and `~/.codeium/windsurf/mcp_config.json`.
    * Restart Windsurf after changes.

    **Env var interpolation:**

    * Use `"${env:LEADMAGIC_API_KEY}"` syntax. Make sure the environment variable is set in your shell profile, not just the current session.
  </Tab>
</Tabs>

## Tool Errors

<AccordionGroup>
  <Accordion title="Tool returns an error response" icon="triangle-exclamation">
    MCP tool errors are returned as `isError: true` with a message. Common causes:

    * **Missing required parameters** — check the [tool reference](/docs/mcp/tools) for required fields.
    * **Invalid parameter format** — emails must be valid format, LinkedIn URLs must be full URLs (e.g., `https://linkedin.com/in/username`).
    * **API rate limit** — wait a moment and try again.
  </Accordion>

  <Accordion title="No data found" icon="magnifying-glass">
    A `not_found` result means LeadMagic doesn't have data for that query. This is **free** — no credits are charged.

    **Tips to improve results:**

    * Use `domain` instead of `company_name` for company lookups.
    * Use LinkedIn profile URLs when available — they're the most reliable identifier.
    * For `find_work_email`, provide both first and last name plus the company domain.
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Is my OAuth token stored on the server?" icon="shield">
    The hosted MCP server uses OAuth bearer tokens for supported clients. Do not paste OAuth client secrets or access tokens into source code, docs, or chats.
  </Accordion>

  <Accordion title="Can multiple team members use the same key?" icon="users">
    Yes, but each person using the key consumes credits from the same account. For team usage, consider using separate keys or an organization account with shared credits.
  </Accordion>

  <Accordion title="What's the difference between MCP and the REST API?" icon="code">
    They use the same underlying API. The MCP server wraps each API endpoint as an MCP tool so AI assistants can call them directly. Credit costs are identical. If you need programmatic access from your own code, use the [REST API](/docs/v1/reference/introduction) directly.
  </Accordion>

  <Accordion title="Does the MCP server support SSE transport?" icon="signal-stream">
    No. The server uses **Streamable HTTP** transport only (MCP 2025 spec). There is no SSE endpoint. Most supported clients work with Streamable HTTP natively. Claude Desktop and Zed use `mcp-remote` to bridge the transport.
  </Accordion>

  <Accordion title="Can I use this with ChatGPT?" icon="comment">
    Yes, use the OAuth-capable remote MCP setup in ChatGPT and connect to `https://mcp.leadmagic.io/mcp`.
  </Accordion>
</AccordionGroup>

## Still Need Help?

<CardGroup cols={2}>
  <Card title="Help Center" icon="life-ring" href="https://help.leadmagic.io/en">
    Contact support for account or billing issues.
  </Card>

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