Connect your own agent to Business Knowledge

Private beta

Business Knowledge is in private beta. If Business Knowledge isn't in your PostHog sidebar, your project isn't in the beta yet. Send feedback in the app.

An agent you build can answer from the same sources PostHog AI and Support use. A support agent, a help desk, a coding agent, or an internal tool connects to Business Knowledge and searches your sources when it needs a fact.

The agent signs in with a project secret API key, not as a PostHog user. It can read the Business Knowledge the key covers. It can't change anything, and it can't read other PostHog data.

There are two ways to connect:

  • MCP – For an agent or framework that supports MCP servers. The agent gets search tools and decides when to use them.
  • REST API – For code that calls search itself and puts the results into a prompt.

Both use the same key.

Connect with MCP

You need to be a project admin to create a key.

  1. Choose what the agent can read

    Required

    A key covers either one library or all the Business Knowledge in the project.

    Give each agent the smallest set it needs. For example, put your public docs in one library for a customer-facing agent, and keep internal policies in another.

  2. Create a key

    Required

    Open Business Knowledge settings and find Connect your agent.

    1. Choose All business knowledge or one library
    2. Enter a name for the key, such as the name of the agent
    3. Click Create key

    For a key that reads one library, you can also open the library on the Libraries tab and create the key under Connect an agent.

    PostHog shows the new key once, inside a ready-to-copy configuration. Copy it before you leave the page.

  3. Add the MCP server to your agent

    Required

    The server URL is https://mcp.posthog.com/mcp/business-knowledge. Send the key in the Authorization header.

    {
    "mcpServers": {
    "business-knowledge": {
    "url": "https://mcp.posthog.com/mcp/business-knowledge",
    "headers": {
    "Authorization": "Bearer <your project secret API key>"
    }
    }
    }
    }

    Most agents and agent frameworks accept the JSON format, including Cursor in .cursor/mcp.json. The URL is the same for every project, in both the US and EU regions. PostHog finds your project and region from the key.

  4. Ask a question

    Checkpoint

    Ask your agent something only your sources can answer, such as your refund policy. The agent searches Business Knowledge and answers from the result.

    If the agent finds nothing, see troubleshooting.

Keep the key on your server

Anyone who has the key can read the Business Knowledge it covers. Don't put it in a website, a mobile app, or a public repository. Store it as a secret in the environment where your agent runs.

For a complete example, see build a support agent.

What the agent can do

The connection gives the agent six read-only tools.

ToolWhat it does
business-knowledge-documents-searchSearches your sources and returns the matching passages
business-knowledge-document-window-retrieveReads the text around a search result
business-knowledge-libraries-listLists the libraries the key covers
business-knowledge-libraries-retrieveGets one library
business-knowledge-repositories-searchFinds files by name and README in your selected GitHub repositories
business-knowledge-repositories-file-retrieveReads a file from a selected repository

The agent can't add, edit, or delete sources, and it has no access to events, persons, insights, or any other PostHog data.

An agent searches more reliably when its system prompt says when to search. For example:

text
Search business knowledge before you answer a question about our product, pricing, or policies.
Answer only from what the search returns, and name the source.
If the search finds nothing, say that you don't know.

Call the REST API

Call the API when your code runs the search itself. The API has the same read-only operations as the MCP tools.

Use the host for your region, us.posthog.com or eu.posthog.com. With a project secret API key you can use @current in place of the project ID.

curl -G "https://us.posthog.com/api/projects/@current/business_knowledge/documents/search/" \
-H "Authorization: Bearer $POSTHOG_BUSINESS_KNOWLEDGE_KEY" \
--data-urlencode "query=How long do refunds take?" \
--data-urlencode "limit=5"

Endpoints

Every endpoint is a GET under /api/projects/@current/business_knowledge/.

EndpointParametersReturns
documents/search/query (required), limit (default 10, maximum 20), rerank (default false), library_idA list of chunks, best match first
documents/{id}/window/around_ordinal (required), radius (default 5, maximum 15)The chunks around one chunk of a document
libraries/NoneThe libraries the key covers
libraries/{id}/NoneOne library
repositories/search/query (required), repo, library_idMatching file paths and README excerpts
repositories/file/repo (required), path (required), library_idThe text of one file
access/NoneThe project ID, and the library the key is limited to

Search results

Each search result is one chunk.

FieldMeaning
contentThe text of the chunk
source_name, source_type, source_idThe source the chunk comes from
document_id, document_title, urlThe document, and the page URL for a URL source
ordinalThe position of the chunk in its document, starting at zero
matched_bykeyword, semantic, both, or context. See how search works.
similarityHow close the chunk is to the query in meaning, from 0 to 1. null when only the keyword lookup found it.
is_generatedtrue for a source learned from support

To read more of a document, pass document_id and ordinal to the window endpoint:

Terminal
curl -G "https://us.posthog.com/api/projects/@current/business_knowledge/documents/<document_id>/window/" \
-H "Authorization: Bearer $POSTHOG_BUSINESS_KNOWLEDGE_KEY" \
--data-urlencode "around_ordinal=4" \
--data-urlencode "radius=3"

What a key covers

ChoiceWhat the agent reads
All business knowledgeEvery source and selected repository in the project, in a library or not
One libraryThe sources and repositories in that library

A key for one library behaves as if nothing else exists:

  • A search with no library_id reads that library
  • A search that passes the ID of another library returns 404. Leave library_id out, or pass the key's own library ID.
  • The list of libraries holds that library only
  • A request to get another library, or to read a document outside the library, also returns 404

A project secret API key that you create in project settings with the business_knowledge:read scope also reads all your Business Knowledge.

The table under Connect your agent lists each key, what it reads, and when an agent last used it.

Roll or delete a key

Roll or delete a key under Project secret API keys in project settings. An agent that uses a deleted key loses access immediately.

If you delete a library, a key limited to that library stops working. Create a new key for another library.

Rate limits

LimitValue
One key480 requests per minute and 4,800 per hour
All keys in a project, combined480 requests per minute and 4,800 per hour

A request over the limit returns 429. Wait and retry.

Troubleshooting

What you seeWhat to check
401 from the MCP URL, with This URL needs a project secret API keyThe Authorization header is missing, or it holds a personal API key. Send Bearer followed by a key that starts with phs_.
400 with A project secret API key connects to .../mcp/business-knowledgeThe agent uses the main MCP URL. Change it to https://mcp.posthog.com/mcp/business-knowledge.
This project secret API key cannot read business knowledgeThe key has no business_knowledge:read scope, or Business Knowledge isn't available in the project. Create a key under Connect your agent.
The library this project secret API key was limited to no longer existsSomeone deleted the library. Create a new key for another library.
Business knowledge belongs to project ID ...The key comes from another environment of the project. Create the key in the project's main environment.
The search returns nothingThe source hasn't passed its content check yet, or it isn't in the library the key covers. Check the same query in the Playground.

How this differs from the main PostHog MCP server

Business Knowledge endpointPostHog MCP server
URLhttps://mcp.posthog.com/mcp/business-knowledgehttps://mcp.posthog.com/mcp
Signs in withA project secret API keyA PostHog user, through OAuth or a personal API key
Built forAn agent you build and run for your customers or teamYour own coding agent or AI client
AccessRead-only Business Knowledge toolsThe PostHog tools your user and scopes allow

Each endpoint accepts only its own kind of credential. A project secret API key doesn't work on the main MCP server, and a personal API key doesn't work on the Business Knowledge endpoint.

Still have questions?

Was this page useful?