MCP for your public users and colleagues

Deploy a hosted MCP server for your Kapa project in a single click to expose your knowledge sources over MCP. As a pre-built integration, it serves two audiences:

• External users in AI tools and editors: More accurate AI responses and a better developer experience: agents in tools like Cursor, Claude Code, or VS Code have up-to-date context about your product, so external users can query your documentation without leaving their editor. This is intended for projects that expose public information only.
• Internal teams in AI tools: More accurate AI responses for your own team: employees can access documentation and internal knowledge sources from tools like ChatGPT or Claude, so sales, support, and solutions teams can get answers without switching context. Access is restricted to team members with Kapa accounts.

Building your own agent?

The same server can act as a building block: an agent you build can call its tools to retrieve knowledge from your documentation. That usage is covered separately in MCP for agents.

Setup and configuration

To set up an MCP server for your Kapa instance:

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.

See Authentication for details on each authentication type.

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

Public (OAuth)

Use this for external users in AI tools and editors. Your server is publicly accessible, but Kapa requires users to authenticate with a Google or GitHub account.

When a user connects for the first time, Kapa presents a provider picker where the user can choose to sign in with Google or GitHub. The selected provider completes an OAuth login. Kapa uses the anonymous user ID from the chosen provider only to enforce per-user rate limits and prevent abuse of your MCP server.

Google

• Kapa requests only the openid scope.
• Receives an ID token (a JWT) that contains a stable, opaque user ID (sub).
• 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. This is Google's generic wording for the openid scope: it means the app can recognize that the same Google account is signing in again. It does not grant access to the user's email, name, contacts, or other data, which would require additional scopes such as email or profile.

GitHub

• Kapa requests no OAuth scopes.
• With no scopes requested, GitHub grants read-only access to public profile information only.
• Kapa uses the stable, opaque GitHub user ID (id) solely for rate limiting.
• Does not access repositories, organizations, email addresses, or other GitHub data.

Internal (Kapa account)

Use this for internal teams in AI tools. 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 permitted for your Kapa instance.

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.

There is a third authentication type, API key, used to connect an agent you are building to your knowledge base. It is covered in MCP for agents.

Rate limits

Public and internal OAuth servers share the same limits, with a separate limit for each tool:

Tool	Per-user limit	Per-team limit
Semantic 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.

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.

The semantic search tool wraps the Retrieval API, which provides the same functionality via a standard HTTP API. For latency characteristics and programmatic configuration, see MCP for agents.

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.

Use cases

External users in AI tools and editors (public MCP)

Your hosted MCP server works with any MCP-compatible AI tool or editor so developers can query your docs without leaving their workflow.

Share your MCP with your external users

If you already have a Website Widget live, you should advertise your MCP server via the MCP install menu in the widget header.

To enable it, follow the steps in Website Widget | Configuration → MCP install menu, which covers all required widget attributes, examples, and behavior.

You should also add a dedicated page to your documentation with setup instructions for popular AI tools. See the page describing the Kapa MCP server for an example.

If you already expose your own MCP server to your users, you can proxy the Kapa server from it, so users install a single server and still get semantic search over your knowledge sources.

Tell your users

Share your MCP on social media, in developer newsletters, or alongside other help resources in your docs. See our guide on Driving Users to MCP for a full playbook.

See the installation instructions for Kapa's own documentation MCP server as an example of how to install Kapa Hosted MCP servers in various clients.

Internal teams in AI tools (internal MCP)

Expose documentation and internal, non-public knowledge sources to your own team inside AI tools like ChatGPT or Claude. Your hosted MCP server works with any MCP-compatible AI tool, allowing employees - such as Solutions Engineers, Customer Success, Sales, and Support - to access accurate, product-specific knowledge without leaving their workflow.

Access is restricted to employees with Kapa accounts, limiting access to projects that include internal knowledge sources.

Connecting your hosted MCP to your AI tools

Follow Kapa's tutorial to Connect your internal hosted MCP to ChatGPT or Claude.

About MCP

If you're new to MCP, the official documentation has a good introduction.

MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems. (Source: What is the Model Context Protocol (MCP)?)

This means that AI assistants and agents can access knowledge and tools beyond their own training data and capabilities. For example:

• AI coding tools like Claude Code and Cursor can connect to a documentation MCP to get up-to-date comprehensive knowledge of a product.
• An AI agent can connect to your calendar, so it can act as a personal assistant.
• An internal company chatbot can connect to company databases and wikis, providing a single interface to pull together datasets.

Kapa's MCP can be used with AI assistants like Claude Code and Cursor, as well as to connect your own agents to your knowledge base.