Skip to main content

Hosted MCP server

Deploy a hosted MCP server for your Kapa project in a single click to expose your knowledge sources over MCP. It can be used in two ways:

  • 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, and ChatGPT have up-to-date context about your product, so users can query your documentation without leaving their editor.

  • Your in-product agents: Agents inside your product can call your MCP tool to tap into deep, product-specific knowledge from your docs and guides, so they can explain features, answer questions, and help users get work done without leaving your product.

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. This controls how clients authenticate with your MCP server:
    • Public – Your server is publicly accessible. Kapa requires users to authenticate with any Google account. Use this for users connecting from AI tools and editors (see Use with AI tools and editors).
    • API key – Your server requires a project API key via the Authorization header. Use this for service and agent integrations (see Use with in-product agents).

There are two other elements that can be configured:

  • Server instructions
  • The semantic retrieval tool name and description: the description helps the LLM know what your tool is for and when to use it.

Kapa provides a default configuration for these elements. This should be suitable for most use cases. If you need to change them, contact support@kapa.ai.

Use with AI tools and editors​

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

Tell your users

Share your MCP on social media, in developer newsletters, or alongside other help resources in your docs.

Authentication​

When a user connects to your public hosted MCP server for the first time, Kapa opens a Google sign-in window and completes an OAuth / OpenID Connect login.

Hosted MCP servers on Kapa:

  • Request only the openid scope from Google.
  • Receive an ID token (a JWT) that contains a stable, opaque user ID (sub).
  • Do not request the email or profile scopes, so Kapa does not see the user’s name, email address, or other personal data.

Kapa uses this anonymous Google ID only to enforce per-user rate limits and prevent abuse of your MCP server:

  • 40 requests per user per hour
  • 200 requests per user per day

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.

Use with in-product agents​

In-product agents are assistants embedded directly into your product, typically as a sidebar inside a webapp that users can open while they work.

What in-product agents usually 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.

Want to see a working example?

Follow our Build an in-product agent tutorial for a hands-on walkthrough using LangGraph and Kapa's MCP server.

In this setup:

  • Native tools handle your own functionality (APIs, mutations, queries, object creation, etc.).
  • The Kapa MCP tool provides product-specific knowledge from your knowledgebase.

Why they need knowledge base context​

In practice, in-product agents almost always need access to your own docs 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 docs.
  • 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 docs 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 MCP tool gives your agent this context.

Authentication​

Your in-product agent authenticates with your hosted MCP server by sending an API key in 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.

Kapa enforces a default rate limit of 60 requests per minute per project for API key–authenticated MCP servers. If you expect higher traffic, contact support@kapa.ai.

Tools provided by Kapa's MCP​

Kapa's hosted MCP server exposes a single semantic search tool:

search_<PRODUCT_NAME>_knowledge_sources

This tool lets AI tools / agents perform semantic retrieval over your product’s documentation and other 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.

Upcoming features​

In future releases, Kapa will add:

  • MCP for internal instances, using Kapa's sign in to authenticate

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.

For now, Kapa's MCP is designed for use with AI assistants like Claude Code and Cursor. Support for building agents and use with Kapa's internal assistant is Coming soon.