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

# MCP Troubleshooting

> Diagnose MCP issues, understand common errors, and try self-service fixes before escalating to your admin.

## Quick Diagnostics

Follow these steps in order to identify your issue:

<Steps>
  <Step title="Is the MCP connected?">
    Go to **Runlayer > My connectors** and check the status:

    * **Active** - Connector is ready to use
    * **Pending** - Awaiting admin approval (contact your admin)
    * **Disabled** - Connector has been disabled (contact your admin)
    * **Error** - Configuration issue (contact your admin)
  </Step>

  <Step title="Is your authentication valid?">
    Go to **Runlayer > My connectors** and find your connector:

    * **Connected** - Authentication is valid
    * **Error/Expired** - You need to revoke and reconnect (see Fix 3 below)
  </Step>

  <Step title="Is the connector selected in your AI client?">
    Some AI clients require you to select which connectors to use for each session or chat:

    * Check your client's MCP/connector settings and verify the connector is enabled
    * In some clients, you must re-select connectors when starting a new chat
    * If tools are missing, try disconnecting and reconnecting the connector from your client
    * If still missing, restart your AI client completely
  </Step>

  <Step title="Did the AI attempt to call the tool?">
    Look for a tool call indicator in your AI client (e.g., "Connected to app", "Using tool", or similar):

    * **If no indicator appears**, the AI client likely didn't try to call Runlayer at all.
    * **If an indicator appears**, expand it to inspect the request and response. This shows exactly what tool was called, what parameters were sent, and what Runlayer returned.
    * **If the response contains your data** but the AI doesn't seem to use it, there may be an issue interpreting the tool response. Try rephrasing or starting a new chat.
  </Step>

  <Step title="Is it a prompting issue?">
    Sometimes the AI just needs a nudge:

    * **Start a new chat** - AI models have a limited "context window" (typically 100-200k characters) that holds everything in your conversation: your messages, AI responses, and all tool results. Long conversations or large tool outputs fill this up, causing the AI to lose track of earlier context or behave erratically. Starting fresh gives the AI a clean slate.
    * **Rephrase your request** - Be more explicit about which tool/connector to use. For example: "Use the `fetch` tool to get the contents of this spreadsheet" instead of just "read this file".
    * **Break it down** - Ask for one thing at a time instead of complex multi-step requests
    * **Wrong tool called?** - LLMs are non-deterministic. Sometimes they call the wrong tool (e.g., fetching metadata instead of file contents). Check the tool call details, then retry with explicit instructions about which tool to use.
  </Step>

  <Step title="Can you reproduce it?">
    Before diving deeper, try the same request again:

    * **Try it again** - AI responses are non-deterministic. The same prompt can succeed on retry.
    * **Try a simpler version** - If "search for Q4 reports and summarize them" fails, try just "search for Q4 reports" first
    * **Note what's consistent** - If it fails every time, it's likely a real issue. If it's intermittent, it may be a prompting or context problem.
  </Step>

  <Step title="Have you tried a different model or AI client?">
    Isolate whether the issue is specific to your setup:

    * **Simplify your connectors** - Too many connected MCPs can overwhelm the AI; disable ones you're not using
    * **Try a different model** - Some models handle tool use better than others. If your AI client supports it, try switching models (e.g., GPT-4o vs Claude Sonnet)
    * **Try a different surface** - Within the same client, try a new chat, a Project, or a different mode (e.g., Agent vs Ask). Some bugs are specific to certain surfaces.
    * **Try a different AI client** - If a tool works in Claude Desktop but not Cursor, the issue may be client-specific
  </Step>
</Steps>

<Tip>
  **Using the right connector?** Some services have multiple MCPs (e.g., Google has GDrive, GDocs, GSheets, GCal, Gmail). Check **Runlayer > My connectors** to compare tools and make sure you're using the connector with the capability you need.
</Tip>

***

## Understanding Error Types

<AccordionGroup>
  <Accordion title="Authentication Errors">
    **Symptoms:** `401 Unauthorized`, `403 Forbidden`, "Authorization failed", "Token expired"

    **Cause:** Your OAuth token has expired, been revoked, or doesn't have the required permissions.

    **Fix:** Revoke and reconnect your authentication (see Fix 3 below).
  </Accordion>

  <Accordion title="Connection Errors">
    **Symptoms:** `Connection timeout`, `Connection refused`, `Network error`, "Server unreachable"

    **Cause:** The MCP server can't be reached due to network issues, firewall rules, or server downtime.

    **Fix:**

    * Check if there's a known outage (ask your admin or check your support channel)
    * Wait a few minutes and try again
    * If persistent, contact your admin
  </Accordion>

  <Accordion title="Claude Code MCP auth fails with certificate issuer error">
    **Symptoms:** Claude Code shows `SDK auth failed: unable to get local issuer certificate` when authenticating a Runlayer MCP.

    **Cause:** Claude Code is making the MCP authentication request itself, outside the Runlayer CLI. In TLS-inspected networks, Claude Code must trust the corporate root CA used by the proxy.

    **Fix:**

    * Install the corporate root CA into the OS trust store
    * Or set `NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem` for the Claude Code process
    * See [Claude Code's enterprise network configuration docs](https://code.claude.com/docs/en/network-config)
  </Accordion>

  <Accordion title="Tool Call Failures">
    **Symptoms:** `MCP error -32603`, `Internal Error`, `500 Server Error`

    **Cause:** The MCP server encountered an error processing your request. This could be a configuration issue, API rate limit, or bug.

    **Fix:**

    * Check audit logs for the specific error message
    * Try the request again with different parameters
    * Contact your admin if it persists
  </Accordion>

  <Accordion title="Permission Denied">
    **Symptoms:** `Access denied`, `Access denied by policy`, `Security violation`, `403`

    **Cause:** You don't have access to this specific tool or data based on your organization's policies.

    **Fix:** Contact your admin to request access to this MCP or tool.
  </Accordion>

  <Accordion title="Rate Limiting">
    **Symptoms:** `429 Too Many Requests`, `Rate limit exceeded: 600 requests per minute`

    **Cause:** Runlayer applies protective rate limits at the MCP gateway to keep one client from overwhelming the proxy or an upstream MCP server. Limits are enforced **per authenticated identity** — the caller's bearer token or `x-runlayer-api-key` is hashed into a stable per-user key, so heavy usage by one user does not consume another user's budget, even when both share an egress IP (corporate VPN/NAT). Unauthenticated requests to public deployment endpoints fall back to per-IP limiting.

    Defaults (platform-managed):

    * **All MCP proxy requests, including `tools/call` and `tools/list`:** 600 requests/minute per identity (\~10 requests/second sustained).

    Limits use a moving-window algorithm, so the budget refills continuously rather than resetting on a fixed clock. When exceeded, the gateway returns `429` with a body like `Rate limit exceeded: 600 requests per minute`.

    **Fix (users):**

    * Wait a few seconds and retry — the window refills continuously.
    * For scripted or agentic clients, add **exponential backoff with jitter** on `429` responses instead of retrying in a tight loop.
    * If you consistently hit the limit during normal use, contact your admin.

    <Note>
      The gateway rate limiter **fails open**: if the limiter's backing store is briefly unavailable, requests are allowed rather than blocked, so a limiter outage never takes down MCP traffic. These ceilings are abuse-protection defaults, not per-agent or per-tool governance quotas — to restrict *which* tools an identity may call, use [access policies](/platform-policies). Self-hosted deployments can tune the default thresholds in configuration; contact your Runlayer account team for guidance.
    </Note>
  </Accordion>

  <Accordion title="Security Violation (False Positive)">
    **Symptoms:** `403 Security Violation`, `Request blocked`, normal requests getting denied

    **Cause:** Runlayer's security scanners flagged your request as suspicious. This can happen when requests contain keywords that look like SQL injection, bulk queries on sensitive fields, or patterns that resemble automated scanning.

    **Fix:**

    * Check audit logs for what was blocked and why
    * Rephrase your request differently
    * Contact your admin with the exact prompt and the blocked tool call details

    **For admins:** confirm it's a false positive by finding the security violation in **Audit Logs** (filter by the user and connector) and reviewing what the scanner flagged. If the request was legitimate, you have three remediation paths:

    * **Lower scanner sensitivity** — globally in **Settings → Security Scanners**, per connector in the connector's security settings, or per client in the **Per-client overrides** section ([sensitivity levels](/runlayer-toolguard#sensitivity-levels))
    * **Change the violation action** from Block to Alert or Mask so requests proceed while still being logged ([violation actions](/runlayer-toolguard#violation-actions))
    * **Disable the specific scanner** (set its action to Allow) if it consistently misfires for your environment
  </Accordion>

  <Accordion title="Domain Whitelisting Required">
    **Symptoms:** Connection errors with Atlassian, Datadog, Asana, HubSpot, or Salesforce MCPs

    **Cause:** Some third-party services require domain whitelisting before accepting connections. Your organization needs to configure Runlayer's OAuth proxy.

    **Fix:** Contact your admin and ask them to configure the OAuth proxy for these services. They'll need to enable it in Settings and add the proxy domain to the service's allowlist.
  </Accordion>

  <Accordion title="Atlassian: agent uses the wrong Jira or Confluence site (multiple tenants)">
    **Symptoms:** Jira or Confluence actions land in the wrong site or space; the agent reads a sandbox tenant instead of production; the agent mixes up Jira and Confluence when both are available; "which site?" ambiguity.

    **Cause:** The official **Atlassian** connector (`mcp.atlassian.com`) serves **both Jira and Confluence through a single OAuth connection**. Every tool call targets a specific site via a `cloudId`, which the agent resolves at runtime with the `getAccessibleAtlassianResources` tool. When your Atlassian account can reach more than one site — for example Jira and Confluence on separate tenants, or a sandbox plus a production instance — the agent can resolve the wrong `cloudId`.

    **Fix (users):**

    * **Name the site explicitly.** Tell the agent which site to use, e.g. "in the `yourco.atlassian.net` site…". For Confluence you can paste the full page URL — the connector converts the site name in the URL to the correct `cloudId`.
    * **Say which product.** If both Jira and Confluence tools are visible and the agent picks the wrong one, be explicit: "use Confluence" or "use Jira".

    **For admins:**

    * **Scope tools with policies.** If an agent only needs one product, use a [policy](/platform-policies) to restrict it to that product's tools (for example, allow only Confluence tools for a docs agent). Fewer overlapping tools means fewer wrong-tool calls.
    * **Separate connectors per tenant.** If your teams keep Jira and Confluence on different Atlassian sites, set up a dedicated Atlassian connector per site so each has its own scoped OAuth connection and a distinct name in the [catalog](/platform-connectors), then bundle the right one into each [Plugin](/platform-plugins).
    * **Pin the site with the community server.** The **Atlassian Community** connector accepts explicit `JIRA_URL` and `CONFLUENCE_URL` configuration, which fixes each connector to a specific site instead of resolving `cloudId` dynamically — useful when users have access to many Atlassian sites.
  </Accordion>

  <Accordion title="Context or Size Limits">
    **Symptoms:** Timeout errors on large files, `500 Server Error` when fetching big documents, truncated responses, AI says "couldn't read the entire file"

    **Cause:** The file or response is too large. This can hit either Runlayer's response size limits or your AI client's context window limits.

    **Fix:**

    * Request a specific range instead of the whole file (e.g., "fetch rows 1-100 from this spreadsheet")
    * Ask for metadata first to understand the file size
    * Break your request into smaller chunks
    * Some AI clients will automatically retry with smaller ranges if the initial request fails
  </Accordion>
</AccordionGroup>

***

## Self-Service Fixes

### Fix 1: Verify MCP Status

Make sure the connector is active and properly configured:

1. Go to **Runlayer > My connectors**
2. Find the connector you're trying to use
3. Check the status:
   * **Active** - Ready to use
   * **Pending** - Waiting for admin approval ([admins: see approval workflow](/platform-approvals))
   * **Disabled/Error** - Contact your admin

***

### Fix 2: Restart or Reconnect Your AI Client

Sometimes the issue is with your AI client's connection to Runlayer, not your app authentication.

**Try these in order:**

1. **Disconnect and reconnect the connector** from within your AI client's settings
2. **Fully quit and reopen** your AI client (don't just close the window)
   * On Mac: Right-click the dock icon → Quit
   * On Windows: Right-click taskbar icon → Close window

<Note>
  Each AI client handles MCP connections differently. Go to **Runlayer > My connectors**, select your connector, click **Add to Client**, and follow the instructions for your client.
</Note>

<Tip>
  **When to reconnect the AI client vs. app authentication:**

  * **Reconnect AI client** when: Tools aren't showing up, or you see "MCP disconnected" errors
  * **Revoke app authentication** (Fix 3) when: You see "401 Unauthorized" or "Token expired" errors
</Tip>

***

### Fix 3: Revoke and Reconnect App Authentication

If the above fixes don't work, try refreshing your OAuth tokens:

<Steps>
  <Step title="Open Runlayer">
    Log in to Runlayer via your SSO/Okta tile
  </Step>

  <Step title="Go to Connectors">
    Click **My connectors** in the left sidebar
  </Step>

  <Step title="Find the connector">
    Locate the connector that's not working
  </Step>

  <Step title="Revoke Access">
    Click the three-dot menu (⋮) and select **Revoke access**
  </Step>

  <Step title="Reconnect">
    Click the **Connect** button to re-authenticate
  </Step>

  <Step title="Complete OAuth">
    Follow the OAuth prompts to grant access again
  </Step>

  <Step title="Test in your AI client">
    Return to your AI client and try the connector again
  </Step>
</Steps>

<Note>
  Your AI client may automatically prompt you to re-authenticate when you try to use the MCP. If so, follow those prompts instead of manually reconnecting in Runlayer.
</Note>

**Why does this happen?** Runlayer refreshes your OAuth tokens automatically in the background, but refreshes can fail in two ways:

* **Transient failures** (provider returns a 5xx error, or the token endpoint is unreachable): Runlayer keeps using your current access token while it's still valid and retries the refresh on subsequent requests. After repeated consecutive refresh failures, the refresh token is treated as exhausted and you must reconnect.
* **Permanent failures** (`invalid_grant` — the provider has revoked or expired the refresh token, or a 401 from the token endpoint): Runlayer clears the stored refresh token immediately, and you must reconnect to re-authenticate.

Admins can see refresh failures — including the failure category (provider error vs. reauthorization required vs. endpoint unreachable) — in [Audit Logs](/platform-audit-logs).

***

## For Administrators

Audit logs are your primary debugging tool. Use them to determine whether an issue is on the Runlayer side or the AI client side.

### Diagnostic Decision Tree

| Audit Log Shows                                | Likely Cause                                        | Action                                        |
| ---------------------------------------------- | --------------------------------------------------- | --------------------------------------------- |
| **No logs for that user/time**                 | AI client never called Runlayer                     | Check connector selection, prompting, VPN     |
| **tool\_call\_success** but user reports issue | AI client received data but didn't use it correctly | AI client issue—user should retry or rephrase |
| **tool\_call\_failure**                        | Runlayer encountered an error                       | Investigate the error message                 |
| **authentication\_error**                      | OAuth token expired or revoked                      | User needs to revoke and reconnect            |

### Using Audit Logs

<Steps>
  <Step title="Navigate to Audit Logs">
    Go to **Runlayer > Audit Logs**
  </Step>

  <Step title="Filter by User">
    Search by the user's email to see their recent activity
  </Step>

  <Step title="Filter by Connector">
    Narrow down to the specific MCP that's having issues
  </Step>

  <Step title="Examine the Details">
    Click into a log entry to see:

    * The exact tool that was called
    * The parameters that were sent
    * The response or error message
  </Step>
</Steps>

**Example audit log entry:**

```json theme={null}
{
  "event_type": "tool_call_failure",
  "server_name": "Gdrive_1",
  "tool_id": "read_file",
  "error": "MCP error -32603: Failed to read file: Internal Error"
}
```

<Warning>
  If you see `500` errors or internal errors consistently, report them to Runlayer support—these indicate bugs that should be fixed.
</Warning>

### Debugging Checklist

When a user reports "it's not working":

1. **Ask for details** - Get the actual prompt, error messages, and tool call details (if visible in their AI client)
2. **Check audit logs** - Is there any activity from this user? What does it show?
3. **Verify connector status** - Is the MCP active? Is the user's authentication valid?
4. **Check for patterns** - Is this affecting one user or many? One MCP or all?
5. **Test reproduction** - Can you reproduce the issue with the same prompt?

For detailed guidance on managing MCPs, approvals, policies, and security monitoring, see [Approvals](/platform-approvals), [Policies](/platform-policies), and [Sessions](/platform-sessions).

***

## Escalation

### User → Admin

When reporting an issue to your admin, include:

* **MCP name**: Which MCP isn't working?
* **What you were trying to do**: Be specific about the action
* **Error message**: Provide a screenshot or a screen recording and include exact tool inputs and outputs if possible
* **Tool call details**: If your AI client shows a tool call indicator, expand it and screenshot the request/response
* **Connector selected?**: Confirm the connector was enabled/selected in your AI client
* **When it started**: Did it ever work? When did it stop?
* **What you've tried**: Revoke/reconnect? Restart client? Verify connector selection?

***

### Admin → Runlayer Support

When escalating to Runlayer support, include:

* **Audit log entry**: ID or screenshot of the relevant log
* **MCP configuration**: Server URL, transport type, auth method
* **AI client**: Which client (and version if known) is the user using?
* **Timeline**: When did the issue start?
* **Scope**: How many users are affected?
* **Steps to reproduce**: How can we recreate the issue?

***

## Prevention Tips

* Keep only MCPs you actively use connected
* Verify your connector is selected/enabled before prompting
* Be explicit in prompts about which tool to use
* Try revoke/reconnect as a first fix for auth issues
* Report issues with specific details and screenshots
* Restart your AI client periodically

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Audit Logs" icon="list" href="/platform-audit-logs">
    Understanding and using audit logs
  </Card>

  <Card title="Security Best Practices" icon="lock" href="/mcp-security-best-practices">
    Security guidelines for MCP usage
  </Card>
</CardGroup>