1. Docs
2. Integrations
3. Model Context Protocol
4. Troubleshooting

Troubleshooting Honeycomb MCP

Beta

Troubleshoot common errors when setting up and using the Honeycomb MCP server.

Introduction 

If you run into issues while integrating with the MCP server, this guide can help. It covers the most common problems users encounter and offers steps to help you resolve them quickly.

Authentication and Setup Issues 

These problems usually occur early, during initial setup or while trying to connect using OAuth or API keys.

OAuth Errors or Failures 

What this means: Some OAuth clients behave inconsistently across environments or platforms, which can interfere with MCP authentication.

What to do: If you experience unpredictable behavior with OAuth-based setup, please open a support ticket or report the issue in the Pollinators Slack Community. We are actively working to improve compatibility and appreciate your input.

Server Connection Problems 

What this means: The MCP server is not responding, or you are unable to establish a connection:

What to do:

• Confirm that you are using the correct endpoint:
  • US: https://mcp.honeycomb.io/mcp
  • EU: https://mcp.eu1.honeycomb.io/mcp
• Make sure that your network allows outbound HTTPS traffic.
• Check whether any proxies or middleware are interfering with HTTPS requests.

API Key Authentication Failures 

What this means: Your client is attempting to use an API key, but the request is being rejected.

This may be due to formatting issues, platform-specific behavior, or missing permissions.

What to do:

• Check the format: Make sure your key is in the form <Key ID>:<Secret Key>. The colon (:) is required.
• Try alternative approaches: API key handling may vary across environments or clients.
  • If you are using mcp-remote, try concatenating the key ID, key secret, and the word Bearer, and passing this via environment variable with string expansion.
  • Try using native HTTP support (in this example, that would mean passing the <Key ID>:<Secret Key> string directly as the Authorization header).
• Check permissions: Make sure that your API key includes the necessary permissions.
• Confirm the key is active: Expired or disabled keys will be rejected.

Connection Issues 

These issues typically occur when your client fails to authenticate, connect, or access MCP tools successfully.

“Unauthorized” Errors 

What this means: Your client attempted to connect to the MCP server but was rejected due to an authentication error.

This can happen when:

• Your API key is invalid or malformed
• Your authentication headers are incorrect
• Your OAuth token is expired or missing

What to do:

If you are using OAuth:

1. Check your active sessions on the Integrations tab of your Honeycomb account (US, EU), and confirm that your session exists and includes the mcp:read scope.
2. Try re-authenticating through your MCP client to refresh the session.

If you are using API keys:

1. Verify both your key ID and key secret.
2. Ensure that your client sets the authentication header correctly. Some clients require the format Bearer id:secret, while others expect a concatenated id:secret string.

No Tools Found or Access Denied 

What this means: You are authenticated, but none of the tools appear, or all tool call fail due to authorization errors.

This often indicates that Honeycomb Intelligence is not enabled for your Team.

What to do: Ask your Team Owner to enable Honeycomb Intelligence in your team settings.

Session Timeouts 

What this means: An agent that previously worked is now failing, often after a period of inactivity.

MCP agent sessions may time out after 24 hours. If your agent suddenly stops responding or tools begin failing, the session may have expired.

What to do: Start a new chat with your agent to re-establish the connection.

Rate Limits 

If your agent returns errors about rate limits, it means you have exceeded the allowed number of requests for your plan.

“Rate Limit Exceeded” Error 

What this means: The MCP server is temporarily rejecting requests due to too many recent calls.

You might receive an error message like: Rate limit exceeded, please try again after <time>.

What to do:

• Wait for the rate limit to reset (the error message typically includes a wait time).
• Consider upgrading your Honeycomb plan if this happens regularly. Rate limits for MCP will be published in a future update.

Tool Issues 

These errors usually happen when your agent tries to use Honeycomb resources it has not verified or for which it does not have context.

Environment, Dataset, or Column Not Found 

What this means: Your agent tried to query something that does not exist, or that it has not confirmed yet.

This is common when an agent makes assumptions about what is available in your Honeycomb team without checking metadata first.

What to do:

You can fix this in a few ways:

• If you are using pre-defined prompts or running agents in unattended workflows, give the agent as much context as possible.
• You can also ‘prime’ the context by asking your agent to list your Honeycomb team information, environments, and datasets.
• Wait. Most agents will retry the query after fetching the correct metadata using available tools.

Submitting Feedback 

You can send feedback about your MCP experience directly to Honeycomb using the feedback tool. Just ask your agent, “Submit feedback to Honeycomb”.

Tips for Prompting 

Your prompt can make a big difference in how well the MCP agent performs. Here are a few practical tips that we have found helpful:

• Use absolute time ranges carefully: Agents default to using relative time (for example, “last 5 minutes”). If you want to specify an absolute time range, ask the agent to calculate and use epoch timestamps. For example: “Use bash to calculate the epoch time of July 10, 2025 11:30 UTC -0400 as my query start time and July 10, 2025 11:35 UTC -0400 as my query end time.” Use this instead of: “Query between 11:30 and 11:35 AM today”.
• Use a rules file for consistent behavior: You can include reusable instructions in a file like CLAUDE.md, .cursorrules. For example, you could instruct the agent to always search for available environments and columns before running a Honeycomb query.