Hosted MCP server

The hosted MCP server is one of the ways to consume Kapa's agentic retrieval: deploy it for your project in a single click, and any MCP-compatible client can search your knowledge sources through its tools. The tools mirror the HTTP Retrieval and Documents endpoints, the other transport for the same retrieval; parameter and result semantics are documented there. One server serves three audiences:

Agents you build: call the server's tools from your own agent. Covered in Connect an AI agent to your knowledge.
External users in AI tools and editors: agents in tools like Cursor, Claude Code, or VS Code get up-to-date context about your product, so users can query your documentation without leaving their editor. Intended for projects that expose public information only.
Internal teams in AI tools: employees access documentation and internal knowledge sources from tools like ChatGPT or Claude. Access is restricted to team members with Kapa accounts.

New to MCP?

MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems. The official documentation has a good introduction.

Setup

Creating a server takes a few clicks, but the subdomain and authentication type are fixed at creation. Set up the MCP server walks through the choices.

Connection

Each server is reachable at a subdomain you configure when creating the integration:

https://<subdomain>.mcp.kapa.ai

The subdomain is set at creation and cannot be changed afterwards. Copy the exact URL any time with Copy MCP server URL in the integration row's Actions column.

Authentication

The authentication type is chosen at creation and cannot be changed afterwards. The three options, as they appear in the platform:

Type	For	Mechanism
API key	Agents and backends you operate	`Authorization: Bearer <API_KEY>` on every request
Public	Your external users, in tools like Cursor or Claude Code	OAuth provider picker (Google or GitHub) on first connect; external projects only
Internal	Your own team, in ChatGPT or Claude	Kapa account login

API key

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.

Public (OAuth)

Your server is publicly accessible, but Kapa requires users to authenticate with a Google or GitHub account. Kapa uses the anonymous user ID from the chosen provider only to enforce per-user rate limits and prevent abuse.

Google: Kapa requests only the openid scope and receives a stable, opaque user ID. It does not request the email or profile scopes, so Kapa does not see the user's name, email address, or other personal data. On the Google consent screen this appears as Associate you with your personal info on Google, which is Google's generic wording for the openid scope.
GitHub: Kapa requests no OAuth scopes, which grants read-only access to public profile information only. Kapa uses the stable, opaque GitHub user ID solely for rate limiting.

Internal (Kapa account)

Your server is restricted to employees with a Kapa account.

When a user connects to your internal MCP for the first time, they are directed to the Kapa login page. The user then logs in with their Kapa account, using whichever authentication methods are permitted for your Kapa team.

To access the internal MCP server, the user account must have the Use Internal Chat Assistant permission for the project. Refer to Roles and permissions for more information on managing project permissions.

Tools

Search tool

The server exposes a search tool that performs agentic retrieval:

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 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 retrieval is multi-step under the hood and tuned for high recall. 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.

Documents tool

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.

Feedback tool

The server also exposes a feedback tool:

give_feedback

This tool:

Lets the agent give your team actionable feedback on your product and documentation (and on the MCP server itself), so issues and suggestions surface where you can act on them.
Is meant to be called when the agent notices something worth flagging while using the other tools, for example an unhelpful or broken search result, an out-of-date document, a product gap, or a server error.
Records the feedback against your Kapa project; it does not retrieve or return knowledge. The agent receives a short confirmation that the feedback was recorded.

It accepts:

message (required) – a description of the problem: what the agent was doing, what went wrong, and any detail that would help fix it.
category (required) – the kind of problem, one of mcp_server, documentation, product, or other.
context (optional) – what the agent was doing when it noticed the problem.
severity (optional) – how much the issue blocked the agent: high, medium, or low.
tool_name (optional) – the tool the feedback is about, if any.

Configuration

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 Customize the MCP tools 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.
The feedback tool: The feedback tool can be configured 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.

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.

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
}

Rate limits

Requests are rate limited with a separate limit for each tool. The per-user limits apply to public and internal OAuth servers; API key servers are limited per team only, across all projects and integrations within the team.

Tool	Per-user limit (OAuth)	Per-team limit
Search tool	300 requests per day	60 requests per minute
Documents tool	300 requests per day	100 requests per minute

If you need higher limits, contact support@kapa.ai.

Setup​

Connection​

Authentication​

API key​

Public (OAuth)​

Internal (Kapa account)​

Tools​

Search tool​

Latency​

Documents tool​

Feedback tool​

Configuration​

Programmatic configuration via _meta​

Search tool parameters​

Documents tool parameters​

User tracking​

Example​

Rate limits​

Setup

Connection

Authentication

API key

Public (OAuth)

Internal (Kapa account)

Tools

Search tool

Latency

Documents tool

Feedback tool

Configuration

Programmatic configuration via `_meta`

Search tool parameters

Documents tool parameters

User tracking

Example

Rate limits