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

# Troubleshooting

> Diagnose and fix the most common GetMCP issues — connection errors, tool failures, auth problems, and more.

## Connection Issues

<AccordionGroup>
  <Accordion title="AI client can't connect / server not found">
    **Symptoms:** Client shows "connection refused", "server not found", or times out on connect.

    **Check these in order:**

    1. Your WordPress site uses **HTTPS** — most MCP clients require it
    2. The server status is **Active** in GetMCP → your server → Settings
    3. The URL is copied exactly (slug and server ID both correct — they're case-sensitive)
    4. WordPress rewrite rules are flushed: go to **Settings → Permalinks** and click **Save Changes** without changing anything
    5. No firewall or security plugin (Wordfence, Cloudflare WAF) is blocking requests to `/mcp/*`

    To confirm the endpoint is reachable, run:

    ```bash theme={null}
    curl -X POST https://yoursite.com/mcp/your-slug \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"ping","params":{}}'
    ```

    A `{"jsonrpc":"2.0","id":1,"result":{}}` response confirms the server is up.
  </Accordion>

  <Accordion title="403 Forbidden">
    **Cause:** Your server has inbound authentication enabled and the client isn't sending the right credential.

    **Fix:**

    * Confirm the `Authorization` header is present in your client config
    * Verify the token matches exactly what's set in **Server Settings → Authentication**
    * If using `mcp-remote` (Claude Desktop), auth must be passed as `--header` args — not as a `headers` key. The `headers` key is not supported by `mcp-remote`:

    ```json theme={null}
    {
      "mcpServers": {
        "my-server": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://yoursite.com/mcp/slug/id",
            "--header",
            "Authorization:Bearer YOUR_KEY"
          ]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="503 Service Unavailable">
    The server is **Paused**. Go to GetMCP → your server → Settings and set the status to **Active**.
  </Accordion>

  <Accordion title="Tools not appearing in the AI client">
    1. Check each tool's status is **Active** (not Paused)
    2. Ask the client to refresh: *"What tools do you have available?"*
    3. In Claude Desktop, fully quit and relaunch — it doesn't hot-reload MCP config
    4. Confirm the server URL in the client config matches your actual server URL
    5. Check **GetMCP → Analytics** — a `tools/list` call should appear after the client connects
  </Accordion>
</AccordionGroup>

***

## Tool Call Failures

<AccordionGroup>
  <Accordion title="Tool returns an error from the upstream API">
    **Symptoms:** Tool call returns `isError: true` with an HTTP error code from your API.

    **Debug steps:**

    1. Open the tool and click **Test** — run it with the same arguments to see the raw request and response
    2. Check that the **Endpoint URL** is correct — try calling it directly with curl
    3. Verify credentials in **Custom Headers** are still valid (tokens expire)
    4. Check that required parameters are mapped to the right location (Path / Query / Body)

    Call logs in **Analytics → Call Logs** show the exact HTTP status returned by your API for every call.
  </Accordion>

  <Accordion title="Missing required argument error">
    The AI didn't supply a required parameter. This usually means the tool description or parameter description wasn't clear enough for the AI to know what value to provide.

    **Fix:**

    * Make parameter descriptions explicit: *"The customer's unique ID, e.g. `cus_abc123`"*
    * If the parameter is always optional in practice, uncheck **Required**
    * See [Best Practices](/docs/best-practices) for writing descriptions that the AI follows reliably
  </Accordion>

  <Accordion title="Wrong value passed to the API (wrong type or format)">
    The AI is sending a value the API rejects — wrong format, wrong type, out of range.

    **Fix:**

    * Add an `enum` to constrain fixed choices
    * Add a `description` that shows the expected format: *"ISO 8601 date string, e.g. `2024-01-15`"*
    * Add `minimum` / `maximum` for numeric ranges
    * Add a `pattern` for regex-validated strings
  </Accordion>

  <Accordion title="Path parameter not substituting into the URL">
    If your URL is `https://api.example.com/users/{{user_id}}` but the request goes to the literal string `/users/{{user_id}}`, the parameter mapping is wrong.

    **Fix:** Open the tool, find the `user_id` parameter in the Input Schema, and set its **Mapping** to **Path**. The placeholder in the URL must match the parameter name exactly including case.
  </Accordion>

  <Accordion title="Request body is empty / parameters not being sent">
    Common causes:

    * Parameter mapping is set to **Query** but your API expects a JSON **Body**
    * HTTP Method is `GET` — GET requests don't have a body; switch to POST or move params to Query
    * JSON body is malformed — use the Test panel to inspect the outgoing request
  </Accordion>

  <Accordion title="Tool response is too large / AI client truncates it">
    Very large API responses slow down AI clients and may be truncated.

    **Options:**

    * Add pagination parameters (`limit`, `page`) and instruct the AI in the description to request smaller pages
    * Use **Response Mapping** to extract only the field you need (e.g. `data.results`) instead of returning the full body
    * Enable **Cache TTL** on read-only tools so the large payload is fetched once and cached
  </Accordion>
</AccordionGroup>

***

## Authentication Issues

<AccordionGroup>
  <Accordion title="API key works in curl but fails through GetMCP">
    **Check the header name exactly.** Header names are case-sensitive on some APIs. If your curl uses `X-API-Key` and the tool header uses `x-api-key`, they may behave differently.

    Also verify there are no leading or trailing spaces in the credential value — these are invisible but cause auth failures.

    Use the **Test** panel → inspect the outgoing request to confirm the header is being sent with the correct value.
  </Accordion>

  <Accordion title="Bearer token expires and tools stop working">
    Static tokens stored in Custom Headers don't refresh automatically.

    **Options:**

    * Use an API key instead of a short-lived bearer token where the upstream API allows it
    * For user-supplied credentials, have users update their MCP client config with the new token
    * For fixed credentials, update the Custom Header in the tool's settings whenever the token rotates
  </Accordion>

  <Accordion title="User-supplied credentials aren't reaching the upstream API">
    If you're using Layer 2 auth (users pass their own key in the client config `headers` block), confirm:

    1. The header name in the client config matches what your API expects (e.g. `X-API-Key`)
    2. GetMCP's server auth is set to **pass-through** or the same header — not overriding it
    3. The tool's Custom Headers don't overwrite the user's header with an empty or default value

    See [Authentication](/docs/guides/authentication) for the full two-layer auth diagram.
  </Accordion>
</AccordionGroup>

***

## Performance Issues

<AccordionGroup>
  <Accordion title="Tool calls are slow">
    **Check in order:**

    1. **Upstream API latency** — test the endpoint directly with curl and time it. If the API is slow, that's the ceiling.
    2. **WordPress server resources** — GetMCP uses `wp_remote_request()` which runs synchronously. A low-resource shared host adds overhead.
    3. **Timeout setting** — if calls are hitting the 30s default timeout, reduce it in Advanced Settings to fail fast instead of hanging
    4. **Enable caching** — for read-only tools that return the same data frequently, set a Cache TTL to avoid repeated upstream calls
  </Accordion>

  <Accordion title="Rate limit errors from upstream API">
    GetMCP's own rate limiter is separate from your upstream API's limits. If your API returns 429s:

    * Reduce the per-server rate limit in GetMCP so calls stay under your API's quota
    * Enable **Cache TTL** on high-traffic read tools to reduce call volume
    * Check Analytics → Call Logs to see which tool is generating the most calls
  </Accordion>
</AccordionGroup>

***

## Analytics & Logs

<AccordionGroup>
  <Accordion title="Call logs not showing up">
    Calls are logged after a tool successfully completes. If logs are empty:

    * Confirm the database tables were created — deactivate and reactivate the plugin to re-run the installer
    * Check that the WordPress user running the site has `CREATE TABLE` privileges
    * Verify calls are actually reaching the server (check your server access logs for POST requests to `/mcp/*`)
  </Accordion>

  <Accordion title="Analytics show errors I don't see in testing">
    The Test panel uses **Test Credentials** (server-level). Production calls from AI clients use **Custom Headers** (production credentials). An error visible in analytics but not in testing usually means the production credential is wrong or expired.
  </Accordion>
</AccordionGroup>

***

## Still Stuck?

If none of the above resolves your issue:

1. Run the ping test from the curl command above to confirm basic connectivity
2. Check **Analytics → Call Logs** for the exact error on the failing call
3. Use **MCP Inspector** to run the call interactively and inspect the raw request/response — see [MCP Inspector](/docs/guides/mcp-inspector)