Connect your own agent to Business Knowledge
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
RequiredA 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
RequiredOpen Business Knowledge settings and find Connect your agent.
- Choose All business knowledge or one library
- Enter a name for the key, such as the name of the agent
- 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
RequiredThe server URL is
https://mcp.posthog.com/mcp/business-knowledge. Send the key in theAuthorizationheader.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. Ask a question
CheckpointAsk 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.
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.
| Tool | What it does |
|---|---|
business-knowledge-documents-search | Searches your sources and returns the matching passages |
business-knowledge-document-window-retrieve | Reads the text around a search result |
business-knowledge-libraries-list | Lists the libraries the key covers |
business-knowledge-libraries-retrieve | Gets one library |
business-knowledge-repositories-search | Finds files by name and README in your selected GitHub repositories |
business-knowledge-repositories-file-retrieve | Reads 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:
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.
Endpoints
Every endpoint is a GET under /api/projects/@current/business_knowledge/.
| Endpoint | Parameters | Returns |
|---|---|---|
documents/search/ | query (required), limit (default 10, maximum 20), rerank (default false), library_id | A 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/ | None | The libraries the key covers |
libraries/{id}/ | None | One library |
repositories/search/ | query (required), repo, library_id | Matching file paths and README excerpts |
repositories/file/ | repo (required), path (required), library_id | The text of one file |
access/ | None | The project ID, and the library the key is limited to |
Search results
Each search result is one chunk.
| Field | Meaning |
|---|---|
content | The text of the chunk |
source_name, source_type, source_id | The source the chunk comes from |
document_id, document_title, url | The document, and the page URL for a URL source |
ordinal | The position of the chunk in its document, starting at zero |
matched_by | keyword, semantic, both, or context. See how search works. |
similarity | How close the chunk is to the query in meaning, from 0 to 1. null when only the keyword lookup found it. |
is_generated | true for a source learned from support |
To read more of a document, pass document_id and ordinal to the window endpoint:
What a key covers
| Choice | What the agent reads |
|---|---|
| All business knowledge | Every source and selected repository in the project, in a library or not |
| One library | The sources and repositories in that library |
A key for one library behaves as if nothing else exists:
- A search with no
library_idreads that library - A search that passes the ID of another library returns
404. Leavelibrary_idout, 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
| Limit | Value |
|---|---|
| One key | 480 requests per minute and 4,800 per hour |
| All keys in a project, combined | 480 requests per minute and 4,800 per hour |
A request over the limit returns 429. Wait and retry.
Troubleshooting
| What you see | What to check |
|---|---|
401 from the MCP URL, with This URL needs a project secret API key | The 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-knowledge | The agent uses the main MCP URL. Change it to https://mcp.posthog.com/mcp/business-knowledge. |
This project secret API key cannot read business knowledge | The 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 exists | Someone 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 nothing | The 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 endpoint | PostHog MCP server | |
|---|---|---|
| URL | https://mcp.posthog.com/mcp/business-knowledge | https://mcp.posthog.com/mcp |
| Signs in with | A project secret API key | A PostHog user, through OAuth or a personal API key |
| Built for | An agent you build and run for your customers or team | Your own coding agent or AI client |
| Access | Read-only Business Knowledge tools | The 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.





