MCP Troubleshooting

Quick Diagnostics

Follow these steps in order to identify your issue:

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)

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)

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

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.

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.

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.

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

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.

Understanding Error Types

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).

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

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

Tool Call Failures

Symptoms: MCP error -32603, Internal Error, 500 Server ErrorCause: 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

Permission Denied

Symptoms: Access denied, Access denied by policy, Security violation, 403Cause: 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.

Rate Limiting

Symptoms: 429 Too Many Requests, Rate limit exceeded: 600 requests per minuteCause: 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.

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. Self-hosted deployments can tune the default thresholds in configuration; contact your Runlayer account team for guidance.

Security Violation (False Positive)

Symptoms: 403 Security Violation, Request blocked, normal requests getting deniedCause: 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)
Change the violation action from Block to Alert or Mask so requests proceed while still being logged (violation actions)
Disable the specific scanner (set its action to Allow) if it consistently misfires for your environment

Domain Whitelisting Required

Symptoms: Connection errors with Atlassian, Datadog, Asana, HubSpot, or Salesforce MCPsCause: 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.

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 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, then bundle the right one into each Plugin.
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.

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

Self-Service Fixes

Fix 1: Verify MCP Status

Make sure the connector is active and properly configured:

Go to Runlayer > My connectors
Find the connector you’re trying to use
Check the status:
- Active - Ready to use
- Pending - Waiting for admin approval (admins: see approval workflow)
- 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:

Disconnect and reconnect the connector from within your AI client’s settings
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

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.

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

Fix 3: Revoke and Reconnect App Authentication

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

Open Runlayer

Go to Connectors

Click My connectors in the left sidebar

Find the connector

Locate the connector that’s not working

Revoke Access

Click the three-dot menu (⋮) and select Revoke access

Reconnect

Click the Connect button to re-authenticate

Complete OAuth

Follow the OAuth prompts to grant access again

Test in your AI client

Return to your AI client and try the connector again

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.

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.

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

Navigate to Audit Logs

Go to Runlayer > Audit Logs

Filter by User

Search by the user’s email to see their recent activity

Filter by Connector

Narrow down to the specific MCP that’s having issues

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

Example audit log entry:

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

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

Debugging Checklist

When a user reports “it’s not working”:

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

For detailed guidance on managing MCPs, approvals, policies, and security monitoring, see Approvals, Policies, and 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

Audit Logs

Understanding and using audit logs

Security Best Practices

Security guidelines for MCP usage

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

MCP Troubleshooting

Quick Diagnostics

Understanding Error Types

Self-Service Fixes

Fix 1: Verify MCP Status

Fix 2: Restart or Reconnect Your AI Client

Fix 3: Revoke and Reconnect App Authentication

For Administrators

Diagnostic Decision Tree

Using Audit Logs

Debugging Checklist

Escalation

User → Admin

Admin → Runlayer Support

Prevention Tips

Audit Logs

Security Best Practices

​Quick Diagnostics

​Understanding Error Types

​Self-Service Fixes

​Fix 1: Verify MCP Status

​Fix 2: Restart or Reconnect Your AI Client

​Fix 3: Revoke and Reconnect App Authentication

​For Administrators

​Diagnostic Decision Tree

​Using Audit Logs

​Debugging Checklist

​Escalation

​User → Admin

​Admin → Runlayer Support

​Prevention Tips

​Related Documentation

Audit Logs

Security Best Practices

Quick Diagnostics

Understanding Error Types

Self-Service Fixes

Fix 1: Verify MCP Status

Fix 2: Restart or Reconnect Your AI Client

Fix 3: Revoke and Reconnect App Authentication

For Administrators

Diagnostic Decision Tree

Using Audit Logs

Debugging Checklist

Escalation

User → Admin

Admin → Runlayer Support

Prevention Tips

Related Documentation