Connecting Agents (MCP)

Honeycomb speaks the Model Context Protocol (MCP), so any MCP-capable agent — a customer-support bot, a sales copilot, an internal assistant — can plug into your organization's memory as a set of tools. Agents read what the organization already knows before they act, and write back what they learn. Everything runs inside your tenant, filtered by Spaces and permissions, exactly like the REST API.

At a glance

• One endpoint: POST /mcp over MCP's Streamable HTTP transport. Stateless — no sessions to manage. GET and DELETE return 405.
• One credential: your API key as Authorization: Bearer hck_.... The key is bound to your tenant server-side; clients never name a tenant.
• Six tools: honeycomb_search, honeycomb_recall, honeycomb_context (read) and honeycomb_ingest, honeycomb_upload, honeycomb_manage (write).
• Reads respect the acting user: pass x-acting-user and read tools only return what that person is allowed to see.
• Writes are private by default: ingested content lands in a private Space unless you explicitly mark it org-wide.
• Same brain as REST: MCP tools and the REST API share one memory, one permission model, one audit surface.

Connect your agent

Point any MCP client at your Honeycomb base URL plus /mcp, with your API key in the Authorization header. A typical client configuration:

{
  "mcpServers": {
    "honeycomb": {
      "type": "http",
      "url": "https://your-honeycomb-host/mcp",
      "headers": {
        "Authorization": "Bearer hck_4Qx7mVbn2wS8kLp0eRtY6uAz"
      }
    }
  }
}

The server is stateless by design: each request is authenticated, scoped, and executed independently, so you can fan out concurrent tool calls from many agents without session bookkeeping.

You can also drive it with plain curl — handy for verifying your key before wiring up an agent:

curl -X POST https://your-honeycomb-host/mcp \
  -H "Authorization: Bearer hck_4Qx7mVbn2wS8kLp0eRtY6uAz" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "honeycomb_search",
      "arguments": { "query": "renewal terms for the Acme contract", "limit": 5 }
    }
  }'

Every tool returns an MCP tool result whose content is a single text block containing pretty-printed JSON — parse that text to get the structured payload.

What happens on every call:

Note: Claude.ai's remote MCP connector uses OAuth instead of an API key. If you're connecting Claude.ai directly, ask your Lua contact to enable the OAuth flow for your organization — everything on this page about the tools is identical.

The six tools

The read tools are idempotent and safe to call freely. honeycomb_manage includes irreversible actions — gate it accordingly in your agent's tool policy.

honeycomb_search

When: the agent needs knowledge but doesn't know which entity it lives on — "what did we promise this customer?", "find the incident postmortem".

Key inputs: query (required), mode (hybrid default, or semantic, keyword, graph, temporal), limit (1–200, default 10), exhaustive (widen the net for "list all" / "how many" questions), and a scope object to filter by namespace, contentType, tags, source, dateRange, or spaceId.

{
  "name": "honeycomb_search",
  "arguments": {
    "query": "open blockers on the Northwind migration",
    "mode": "hybrid",
    "limit": 5,
    "scope": { "namespace": "engineering", "contentType": ["ticket", "meeting_notes"] }
  }
}

Returns: results[] — each with content, score, title, namespace, contentType, tags, validity dates, and linked entities — plus totalFound and searchTimeMs. Use keyword mode when hunting exact IDs or codes; use graph for relationship questions. See Search & Recall for retrieval semantics.

honeycomb_recall

When: the agent knows who or what it's dealing with and wants the dossier — before replying to a customer, reviewing a deal, or handling a repeat request.

Key inputs: entity (name or ID, case-insensitive), options.depth (summary default, full, or relationships), options.query (rank memories by relevance instead of recency), options.timeframe, options.memoryLimit (default 50).

{
  "name": "honeycomb_recall",
  "arguments": {
    "entity": "Elena Vasquez",
    "options": { "depth": "full", "query": "onboarding" }
  }
}

Returns: the entity profile (type, attributes, first seen, mention count), currentFacts, memories grouped by type, and — at full depth — timeline, relationships, and recentMentions.

honeycomb_context

When: at the start of a task, before the agent does anything else. One call replaces a scatter of searches: it assembles entity summaries, relevant policies, recent interactions, and active flags into a single briefing.

Key inputs: task (e.g. customer_interaction, deal_review, support_escalation), entities (names to include), namespace (scopes which policies apply), maxTokens (cap the briefing size for your agent's context window).

{
  "name": "honeycomb_context",
  "arguments": {
    "task": "support_escalation",
    "entities": ["Acme Corp", "ticket-4821"],
    "namespace": "support",
    "maxTokens": 4000
  }
}

Returns: a briefing object — entitySummaries[], relevantPolicies[], recentInteractions[], activeFlags[] — structured for direct injection into a prompt.

honeycomb_ingest

When: the agent learned something worth keeping — a resolved ticket, a decision, a customer preference, a call summary. Ingest it and Honeycomb chunks, embeds, indexes, and extracts entities, facts, and memories automatically.

Key inputs — metadata.namespace, metadata.contentType, and metadata.sourceAgent are required:

{
  "name": "honeycomb_ingest",
  "arguments": {
    "content": "Acme renewed for 24 months at $180k ARR. Owner: Elena. Blocker: SSO rollout must land before Q3.",
    "metadata": {
      "namespace": "sales",
      "contentType": "deal_note",
      "sourceAgent": "sales-copilot",
      "source": "hubspot",
      "externalRef": "hubspot:deal:5591",
      "tags": ["renewal", "acme"]
    },
    "options": { "extractionTier": 1, "onConflict": "supersede" }
  }
}

Returns: id, chunksCreated, entitiesExtracted, factsRecorded, memoriesExtracted, and deduplicated when identical content was skipped. If your agent already extracted structure itself, pass options.entities, options.facts, or options.memories to skip re-extraction.

Warning: Writes fail closed to private. Unless you set orgWide: true (or route into a Space via spaceId), new content is quarantined to a private Space that only appropriately-granted users can read. This protects you from accidentally publishing one user's conversation to the whole organization — see Spaces & Permissions.

honeycomb_upload

When: the knowledge is a file, not text — a contract PDF, a spec DOCX, a CSV export. The file's text is extracted server-side, then ingested exactly like honeycomb_ingest.

Key inputs: fileContent (base64-encoded bytes, up to 10 MB decoded), fileName (the extension selects the parser), and the same metadata as ingest. Supported formats: .pdf, .docx, .doc, .txt, .csv, .md, .json.

{
  "name": "honeycomb_upload",
  "arguments": {
    "fileName": "Q1-report.pdf",
    "fileContent": "JVBERi0xLjQKJc...base64...",
    "metadata": { "namespace": "finance", "contentType": "report", "sourceAgent": "finance-bot" }
  }
}

Returns: the ingest result plus filename, fileSizeBytes, and textLength. Guard failures (bad base64, empty file, oversize, unextractable text) come back as a tool result with isError: true and an error message — not an HTTP error — so your agent can recover gracefully.

honeycomb_manage

When: memory needs correcting — stale entries, duplicates, content a user asked you to forget.

{
  "name": "honeycomb_manage",
  "arguments": { "action": "forget", "entityName": "John Smith", "memoryType": "preference" }
}

Returns: { "action": "...", "affected": 3 }. Prefer archive over delete unless you truly need the data gone.

Patterns that work

Read before acting, write what you learn

The highest-leverage agent loop is simple: brief yourself, act, then bank the outcome.

1. Call honeycomb_context with the task and known entities — one call, one briefing.
2. Call honeycomb_recall for any entity that needs depth; fall back to honeycomb_search for open questions.
3. Do the work.
4. Call honeycomb_ingest with a conversation_summary, deal_note, or ticket — always with an externalRef so re-runs dedup instead of duplicating.

Acting on behalf of a user

When your agent serves a specific person, tell Honeycomb who — add the x-acting-user header (an email or user ID) alongside your API key:

-H "Authorization: Bearer hck_4Qx7mVbn2wS8kLp0eRtY6uAz" \
-H "x-acting-user: [email protected]"

Read tools then return only what that user may see: org-public knowledge plus the Spaces they've been granted. Two agents asking the same question on behalf of two different users can get different answers — that's the permission model working.

Note: This header is honored only when your API key was minted with the act-as-user capability. And the model fails closed: if permission enforcement is active and no acting user resolves, reads return org-public knowledge only — never the full tenant. If your agent seems to "know less" than expected, check that it's sending the acting user. Deployments that require verified identity accept a signed x-acting-user-assertion JWT instead — see Security.

Why agent N+1 is cheaper than agent 1

Your first agent pays the setup cost: connecting data sources, establishing namespaces, letting the entity graph warm up. Every agent after that inherits all of it for the price of one API key.

• No cold start. Agent N+1's first honeycomb_recall on a customer returns years of history it never witnessed, because agents 1 through N (and your connectors) already wrote it.
• No per-agent silos. A fact learned by the support agent is instantly available to the sales copilot — same entities, same graph, no sync jobs between agent memories.
• No per-agent permission systems. Spaces and acting-user scoping are enforced by Honeycomb, once, for every agent. New agents can't accidentally over-share.
• Compounding returns. Each agent's honeycomb_ingest calls make every other agent smarter. Memory is the asset; agents are interchangeable consumers of it.

You can watch this in the console: the Timeline and Entity pages show entries flowing in from each sourceAgent, and Sources shows connector activity side by side with agent writes. See The Console.

Errors and limits

Tool-level validation problems (a missing required field for a manage action, an oversized upload) surface as JSON-RPC errors or isError tool results rather than HTTP failures, so your agent framework can handle them in-band.

Next steps

• Search & Recall — retrieval modes, scoring, and scoping in depth.
• Ingesting Data — content types, extraction tiers, dedup, and versioning.
• Spaces & Permissions — how reads are scoped and how sharing works.
• API Reference — the REST surface (/api/v1/*), including /api/v1/ask, which has no MCP equivalent.