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 a semantic search tool that gives your agent access to your documentation and guides, so it can answer product questions alongside its other capabilities. The Retrieval API endpoint provides 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.
• Semantic retrieval tool name and description: How the tool appears to AI tools and agents, which is what they use to decide when to call it. See Customizing the tool name and description for when to change these and when to leave the default.
• 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 customize the tool name and description under Advanced configuration in 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

API key access is rate limited to 60 requests per minute per team. The limit applies across all projects and integrations within the team. If you need higher limits, contact support@kapa.ai.

The semantic search tool

The server exposes a single 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.

Customizing the tool name and description

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

How an agent sees the tool

When a client connects, it loads the 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 tool, which tool to call, and what to pass as the query.

The name and description therefore determine whether your knowledge base is used at all.

When customizing helps

• The tool searches something other than your product documentation. The default description is written for the most common setup, indexing the knowledge sources that document your product, so it is 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 tool searches. Rename the tool and rewrite the description 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 default does not mention, adding those terms to the description improves the chance the model reaches for the tool on a relevant question.
• You want to frame the tool's job differently. By default the 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 the 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 the description is safe at any time: connected clients pick it up on their next tool refresh. Changing the 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.

Latency

The MCP server 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.

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 retrieval behavior and track end users. These parameters are not part of the tool's input schema, 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.

Retrieval 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.

User tracking

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.

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.