Skip to main content

​
Quick Diagnostics

Follow these steps in order to identify your issue:
1

Is the MCP connected?

Go to Runlayer > MCPs and check the status:
  • Active - MCP is ready to use
  • Pending - Awaiting admin approval (contact your admin)
  • Disabled - MCP has been disabled (contact your admin)
  • Error - Configuration issue (contact your admin)
2

Is your authentication valid?

Go to Runlayer > Connectors and find your MCP:
  • Connected - Authentication is valid
  • Error/Expired - You need to revoke and reconnect (see Fix 3 below)
3

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 MCP from your client
  • If still missing, restart your AI client completely
4

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

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/MCP 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.
6

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

Have you tried a different model or AI client?

Isolate whether the issue is specific to your setup:
  • Simplify your MCPs - 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 MCP? Some services have multiple MCPs (e.g., Google has GDrive, GDocs, GSheets, GCal, Gmail). Check Runlayer > Catalog to see each MCP’s tools and make sure you’re using the one with the capability you need.

​
Understanding Error Types

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).
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
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
Symptoms: Policy denied, Access denied, 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.
Symptoms: 429 Too Many Requests, Rate limit exceededCause: You or your organization has made too many requests in a short period of time.Fix: Wait a few minutes before trying again. If you consistently hit rate limits, contact your admin.
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 - they can review false positives, adjust scanner sensitivity, or whitelist your use case
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.
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 MCP is active and properly configured:
  1. Go to Runlayer > MCPs
  2. Find the MCP you’re trying to use
  3. Check the status:

​
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 MCP 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
Each AI client handles MCP connections differently. Go to Runlayer > Connectors, select your connector, click Add to MCP 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:
1

Open Runlayer

Log in to Runlayer via your SSO/Okta tile
2

Go to Connectors

Click Connectors in the left sidebar
3

Find the MCP

Locate the MCP that’s not working
4

Revoke Access

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

Reconnect

Click the Connect button to re-authenticate
6

Complete OAuth

Follow the OAuth prompts to grant access again
7

Test in your AI client

Return to your AI client and try the MCP 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.

​
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 ShowsLikely CauseAction
No logs for that user/timeAI client never called RunlayerCheck connector selection, prompting, VPN
tool_call_success but user reports issueAI client received data but didn’t use it correctlyAI client issue—user should retry or rephrase
tool_call_failureRunlayer encountered an errorInvestigate the error message
authentication_errorOAuth token expired or revokedUser needs to revoke and reconnect

​
Using Audit Logs

1

Navigate to Audit Logs

Go to Runlayer > Audit Logs
2

Filter by User

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

Filter by Connector

Narrow down to the specific MCP that’s having issues
4

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”:
  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 the Admin Handbook.

​
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

Employee Handbook

Getting started with MCPs and making requests

Admin Handbook

Managing approvals, policies, and security

Audit Logs

Understanding and using audit logs

Security Best Practices

Security guidelines for MCP usage