Building with Kapa

There are two ways to put Kapa in front of your users: deploy a pre-built integration that works out of the box, or use Kapa as a building block for experiences you build yourself. This section covers building your own. Everything here runs on the same knowledge base as the pre-built integrations, but you control the experience in code.

If you are building an in-product agent, start with In-Product Agents for a comparison of the two approaches: building the agent end-to-end with the Agent SDK, or connecting an agent you already have to your knowledge base.

Integration options

Integration Method	Best For	Complexity	Features
Agent SDK	In-product agents with tool calling	Low	Streaming, custom tools, human-in-the-loop approval, full chat UI or headless
MCP for agents	Knowledge retrieval for agents you own	Very low	Works with any MCP-capable agent framework, no integration code to write
Chat SDK	Chat interfaces in React apps	Low	Full control over UI, built-in support for streaming, state management
HTTP API	Any platform or language	Medium	Maximum flexibility, retrieval, chat, and analytics endpoints

Agent SDK

The Kapa Agent SDK lets you embed an AI agent in your product that can answer questions from your knowledge base and take actions through custom tools. The agent runs a multi-turn loop: it streams responses, calls tools (with optional user approval), and continues until it has a final answer. Knowledge base search is built in, so there is no retrieval system for you to set up. Available as two packages:

@kapaai/agent-core: Pure TypeScript, works with any framework or none
@kapaai/agent-react: React components and hooks with a ready-made chat UI

import { AgentProvider, AgentChat } from "@kapaai/agent-react";

function App() {
  return (
    <AgentProvider
      getSessionToken={async () => {
        const res = await fetch("/api/session", { method: "POST" });
        return res.json();
      }}
      projectId="your-project-id"
      integrationId="your-integration-id"
    >
      <AgentChat branding={{ title: "AI Assistant" }} />
    </AgentProvider>
  );
}

Get started with the Agent SDK →

MCP for agents

If you already have an agent built with a framework like LangGraph, OpenAI Agents, or your own orchestration layer, you can connect it to your knowledge base over MCP. Kapa's hosted MCP server exposes a semantic search tool that gives your agent retrieval over your documentation and other knowledge sources, with no retrieval pipeline for you to build or operate.

result = await session.call_tool(
    name="search_acme_knowledge_sources",
    arguments={"query": "How do I configure SSO?"},
)

Get started with MCP for agents →

Chat SDK

The Kapa Chat SDK (@kapaai/react-sdk) provides React components and hooks for integrating Kapa's conversational AI capabilities into your React applications. It is especially useful because it is designed to work without having to wire up a custom backend/proxy. It can run fully client-side, simplifying implementation. It is ideal for developers who want to:

Create custom chat interfaces with their own UI/UX
Manage conversation state with React hooks
Collect user feedback on AI responses
Stream AI responses in real-time

import { KapaProvider, useChat } from "@kapaai/react-sdk";

function ChatComponent() {
  const { submitQuery, conversation } = useChat();
  // Build your custom chat interface
}

Get started with the Chat SDK →

HTTP API

The Kapa HTTP API provides direct access to Kapa's capabilities through HTTP endpoints. It offers Chat endpoints for full question answering, a Retrieval endpoint for semantic search without LLM generation (the same retrieval that backs the MCP server), and analytics endpoints for exporting conversations and usage data from the Kapa platform, regardless of which integrations produced them. It is ideal for:

Integration with any programming language or platform
Backend integrations or middleware
Exporting conversation and usage data into your own systems
Custom implementations requiring flexible API interactions

curl -X POST "https://api.kapa.ai/query" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_id": "<INTEGRATION_ID>",
    "query": "How to get started?"
}'

Get started with the HTTP API →

Which integration method should I choose?

Choose the Agent SDK if you are building an in-product agent with custom tools, approval flows, or need the agent to take actions on behalf of users.
Choose MCP if you already have an agent or are building one on your own framework, and you want to add knowledge base search to it. Most agent frameworks support MCP tool calling out of the box, so there is no integration code to write.
Choose the Chat SDK if you want a more custom chat UI than the Website Widget for Q&A over your knowledge base, and you do not need custom tools or a backend. It runs fully client-side with built-in bot protection, which makes it a fit for public websites.
Choose the HTTP API if you need maximum flexibility, are using a different frontend framework, or are integrating Kapa on the backend. The Retrieval endpoint is the direct HTTP alternative to MCP.

Integration options​

Agent SDK​

MCP for agents​

Chat SDK​

HTTP API​

Which integration method should I choose?​