Skip to main content
If you run into issues while integrating with the MCP server, this guide can help. It covers the most common problems you may 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, 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 calls 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.

​
”Rate Limit Exceeded” error

What this means: The MCP server is temporarily rejecting requests due to too many recent calls. Per-tool limits vary: most tools share a default of 50 calls per minute, discovery and metadata tools allow higher limits, and expensive or mutating tools (like get_service_map, create_trigger, and canvas_agent_invoke) have lower limits. Rate limits are tied to your authentication method. API key limits apply to all requests made with that key. OAuth limits are per-user, shared across all sessions for that user. To explore the full per-tool matrix, visit Rate Limits and Scopes. 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.

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

​
Agent can’t create or update Boards, Triggers, or SLOs

What this means: The agent reports a permission error when calling a write tool like create_board, update_board, create_trigger, update_slo, or create_recipient. This usually indicates that the agent’s connection does not include the mcp:write scope. What to do:
  • OAuth connections: Re-authorize the agent and grant write access during the consent flow.
  • API key connections: Confirm that the API key has the Write permission under Model Context Protocol and that the Environments scope grants access to the target environment. To explore the full list of tools that require write scope, visit the MCP Tools Reference.

​
Submitting feedback

If something is not working as expected or you have ideas for improvement, you can send feedback directly to Honeycomb from your agent using the feedback tool. Just ask your agent, “Submit feedback to Honeycomb”.

​
Tips for prompting

Small changes to how you prompt your agent can prevent the most common tool failures and get you to useful results faster. Here are a few practical tips:
  • 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.