MCP for agents

If you are building an agent, you can connect it to your knowledge base over MCP. Kapa's hosted MCP server exposes two retrieval tools: a semantic search tool that gives your agent access to your documentation and guides, so it can answer product questions alongside its other capabilities, and an optional documents tool for fetching full pages. The Retrieval APIs provide the same functionality over plain HTTP, if your stack does not speak MCP.

This page covers using the MCP server as a building block inside an agent you operate. If you instead want to offer an MCP server to your external users (in tools like Cursor or Claude Code) or to your internal team (in ChatGPT or Claude), see MCP for users.

Want a ready-made agent experience?

The Kapa Agent SDK provides a complete in-product agent with streaming, custom tools, human-in-the-loop approval, and a full chat UI out of the box. Knowledge base search is built in, no MCP setup needed.

Setup and configuration

Your agent connects to a Hosted MCP server with API key authentication. To create one:

1. In Kapa, click Integrations > + Add new integration.
2. Choose Hosted MCP Server.
3. Click Continue.
4. Configure the Subdomain: This becomes the first part of the URL clients use to connect to your MCP server, in the form <subdomain>.mcp.kapa.ai.
5. Configure the Server name. This becomes the MCP server label (server_name / serverLabel) that clients see when listing or calling tools from this server; it does not affect the URL or subdomain.
6. Choose the Authentication type.

For this use case, choose API key as the authentication type. The other authentication types (public and internal OAuth) are for offering the server to people in their AI tools; they are covered in MCP for users.

There are additional elements that can be configured:

• Server instructions: Custom instructions for the MCP server.
• Tool names and descriptions: How the tools appear to AI tools and agents, which is what they use to decide when to call them. See Customizing the tool names and descriptions for when to change these and when to leave the defaults.
• The documents tool: The optional documents tool is disabled by default and can be enabled per integration.
• Source groups: Restrict the server to only return results from specific source groups. When configured, the server only searches sources in the selected groups (plus any global sources), regardless of what clients request. See Hosted MCP server configuration for details.

Kapa provides a default configuration that is suitable for most use cases. You can enable the documents tool and customize the tool names and descriptions in the Tools section of your MCP integration settings. To change the server instructions, contact support@kapa.ai.

Authentication

Your server requires a project API key via the Authorization header on every request:

Authorization: Bearer <YOUR_API_KEY>

How you set this header depends on the MCP client or agent framework you use, but in all cases you must keep the API key in your backend. Never expose it in client-side code or send it to the browser.

Rate limits

Requests to your MCP server are rate limited per team, with a separate limit for each tool:

Tool	Per-team limit
Semantic search tool	60 requests per minute
Documents tool	100 requests per minute

The limits apply across all projects and integrations within the team. If you need higher limits, contact support@kapa.ai.

Tools

The server exposes two tools: the semantic search tool, which is always available, and the documents tool, which is optional and disabled by default.

The semantic search tool

The server exposes a semantic search tool:

search_<PRODUCT_NAME>_knowledge_sources

This tool:

• Searches all knowledge sources connected to your Kapa project for a given query.
• Returns the most relevant chunks, in descending order of relevance.
• Each chunk is a short, self-contained snippet of text taken from a single page or item (for example, part of a documentation page).

Results are returned as a structured list of objects with:

• source_url – the URL of the original source.
• content – the chunk content in Markdown.

Latency

The semantic search tool wraps the Retrieval API and has the same typical latency:

• p50: ~3 seconds
• p95: ~4.5 seconds

This is higher than a simple embedding-based or keyword search because the underlying retrieval pipeline is multi-step and tuned for high recall. For each tool call, the pipeline runs multiple search iterations using both embedding-based and sparse retrieval. Query decomposition and keyword generation produce the queries for these iterations, and reranking is used to refine relevance. The tradeoff is fewer missed-but-relevant chunks at the cost of higher latency.

Enabling use_pruning adds one more model call at the end of this pipeline, which costs roughly another 0.7 seconds per query.

The documents tool (optional)

The server can optionally expose a documents tool:

get_<PRODUCT_NAME>_knowledge_documents

This tool:

• Fetches full documents from your knowledge sources by their exact source URL.
• Returns the full content of each matched document in Markdown; requested URLs that do not match exactly are omitted, so results may be empty.
• Paginates the results and truncates long documents, so that fetching many or large documents does not flood the agent's context window. If the agent wants to see more, it can page through the results with page and page_size, and increase max_chars_per_document to fetch more of a single document.
• Is meant for looking up the content of one or more specific documents, for example when the agent needs the complete page rather than the short chunks the search tool returns.

Results are returned as a structured list of objects with:

• source_url – the URL of the document.
• title – the title of the document.
• content – the document content in Markdown, truncated to max_chars_per_document.

The documents tool is disabled by default. Enable it in the hosted MCP integration settings.

Customizing the tool names and descriptions

By default, Kapa exposes the semantic search tool as search_<PRODUCT_NAME>_knowledge_sources and the documents tool as get_<PRODUCT_NAME>_knowledge_documents, each with a description written to work well across clients. These defaults are a good fit for most projects, so change a tool name or description only when you have a concrete reason to (see When customizing helps); otherwise, leave them as is. You can change both in the Tools section of your MCP integration settings, where the current default descriptions are also shown. Before you do, it helps to understand what the model actually sees.

How an agent sees the tools

When a client connects, it loads each tool's name, description, and input schema into the model's context window, alongside every other tool available in that client or agent. During generation, the model relies on that text, and only that text, to decide whether to call your tools, which tool to call, and what arguments to pass.

The names and descriptions therefore determine whether your knowledge base is used at all.

When customizing helps

• The tools search something other than your product documentation. The default descriptions are written for the most common setup, indexing the knowledge sources that document your product, so they are framed around your product. If your server instead indexes a different collection, for example internal go-to-market material or the documentation for your engineering team's upstream dependencies, that framing no longer describes what the tools search. Rename the tools and rewrite the descriptions so they tell the client what the collection actually contains.
• Your users and agent use different vocabulary than the default. If people refer to your documentation by a specific name, or your product has terms the defaults do not mention, adding those terms to the descriptions improves the chance the model reaches for the tools on a relevant question.
• You want to frame a tool's job differently. By default the search tool description tells the model to use the tool for questions about your product. You might want a different policy, for example calling it regardless of user intent, or using it only as a last resort. The description is where you set that expectation. This behavior is usually split between the tool description and the surrounding instructions, whether that is the system prompt in an agent you build or a skill in a client like Claude Code, but the tool description often carries part of it.

When you do change a description, keep it concise. It is sent on every request, so a long description spends tokens and can dilute the signal that makes the model choose the tool.

Renaming is disruptive, re-describing is safe

Changing a description is safe at any time: connected clients pick it up on their next tool refresh. Changing a tool name is a breaking change for clients that already cached the old name. Agents will not find the tool until they reconnect and rediscover tools, and any tool name hard-coded in your code or _meta calls must be updated. Treat a name change like an API change that you roll out deliberately. The same logic applies to the optional documents tool: enabling it carries no risk, but disabling it once agents rely on it is a breaking change.

Programmatic configuration via _meta

When integrating the Kapa MCP server into your agent via code, you can pass additional parameters via the MCP _meta field to control tool behavior and track end users. These parameters are not part of the tools' input schemas, so they are set directly in your code and are not visible to tool-calling models.

note

These parameters require an API key authenticated MCP server and are not available for public or internal OAuth-authenticated servers, as they are set by developers at API call time.

Semantic search tool parameters

Parameter	Type	Description
use_pruning	boolean, optional	Optionally prune low relevance chunks after retrieval, at the cost of added latency. The number of returned chunks becomes variable and may be significantly lower than top_k; pruning always keeps the 2 most relevant chunks where top_k and max_chars permit. Defaults to false. Read about how it works in How we prune RAG context.
top_k	integer (1-15), optional	The maximum number of chunks to return. Fewer may be returned if max_chars or use_pruning reduce the result set. Defaults to 15.
max_chars	integer (1-60000), optional	Maximum number of characters across all returned chunks. Chunks are included in order of relevance, but only up to the point where the total character count stays within this limit. Chunks are never truncated. This is an upper bound, not a target: especially with use_pruning enabled, the returned total may be well below this limit. Defaults to 35,000.
source_ids_include	array of UUIDs, optional	Only return results from these specific sources.
source_group_ids_include	array of UUIDs, optional	Only return results from sources in these groups. If the server is also configured with source groups, the intersection of the two lists is used.
redact_query	boolean, optional	If true, the query text is redacted from analytics. Use for sensitive queries.

Documents tool parameters

Parameter	Type	Description
source_group_ids_include	array of UUIDs, optional	Only return documents from sources in these groups.

User tracking

User tracking is shared across both tools. To associate queries with end users in your analytics, you can optionally pass a user object. This information appears in your dashboards at app.kapa.ai.

Parameter	Type	Description
user.email	string, optional	User's email address.
user.unique_client_id	string, optional	Your own identifier for the user (e.g., an ID from your system), useful for linking Kapa analytics with your internal data.
user.company_name	string, optional	User's company name.
user.first_name	string, optional	User's first name.
user.last_name	string, optional	User's last name.

Example

The exact pattern for setting _meta parameters will depend on your agent framework and codebase. Here is how you pass them at the call site using the MCP Python SDK:

result = await session.call_tool(
    name="search_acme_knowledge_sources",
    # Dynamic argument - provided by your agent or user input
    arguments={"query": "How do I configure SSO?"},
    # Meta parameters - preset configuration controlled by your code
    # The SDK automatically maps this field to `_meta` in the JSON-RPC request
    meta={
        "top_k": 5,
        "max_chars": 35_000,
        "source_ids_include": ["550e8400-e29b-41d4-a716-446655440000"],
        "source_group_ids_include": ["86ee1d82-d96e-4219-9290-b2a07d3abd8d"],
        "user": {
            "email": current_user.email,
            "unique_client_id": current_user.id,
        },
    },
)

For raw JSON-RPC requests (e.g., from n8n), use _meta (with underscore) directly:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_acme_knowledge_sources",
    "arguments": {"query": "How do I configure SSO?"},
    "_meta": {
      "top_k": 5,
      "max_chars": 35000,
      "source_ids_include": ["550e8400-e29b-41d4-a716-446655440000"],
      "source_group_ids_include": ["86ee1d82-d96e-4219-9290-b2a07d3abd8d"]
    }
  },
  "id": 1
}

What agents typically do

Common patterns include:

• Data and operations: Run queries, inspect entities, or pull recent activity using your own APIs.
• Creating assets and workflows: Generate dashboards, data pipelines, or analytics notebooks on behalf of the user.
• Debugging and guidance: Investigate failed runs or errors and return a structured explanation or fix plan.
• Product help: Answer "How do I…?" questions about features, configuration, and best practices.

Agents are typically powered by a reasoning model that can call tools, often orchestrated by an agent framework such as OpenAI's Agent Builder, LangGraph, or a lightweight in-house orchestration layer.

In this setup:

• Native tools handle your own functionality (APIs, mutations, queries, object creation, and so on).
• The Kapa semantic search tool provides product-specific knowledge from your knowledge base, and the optional documents tool lets the agent fetch complete pages when it needs them.

Why agents need knowledge base context

In practice, in-product agents almost always need access to your own documentation and knowledge sources:

• Users naturally ask knowledge questions ("How do I set this up?", "What does this error mean?") directly in the chat, and those answers live in your documentation.
• Interactions with native tools often trigger follow-up questions ("Why did this query fail?", "What does this setting do?") that require documentation to explain.
• The reasoning model itself sometimes needs documentation to use tools correctly. For example, learning how to write queries in a product-specific language, understanding valid parameters, or interpreting and fixing errors returned by other tools.

The Kapa semantic search tool gives your agent this context. See our research on knowledge base search in agents for more on this.

For a hands-on walkthrough using LangGraph and Kapa's MCP server, follow the Connect your agent to your documentation with MCP tutorial. Once connected, Tuning knowledge base search for your agent covers retrieval size, pruning, and prompting.