Skip to main content

Set up with a coding agent

In this tutorial, you use a coding agent, such as Claude Code or Cursor, to set up a fresh Kapa project. If you prefer to go through each step yourself, follow Index a source in the dashboard instead.

For this, you install the Kapa plugin in your coding agent. The plugin connects the agent to the Kapa platform MCP server, so it can call the Kapa platform API on your behalf. It also installs skills that teach the agent how to use that API for tasks such as setting up each source type.

By the end of this tutorial, you will have:

  • A knowledge source in your Kapa project, with its content searchable.
  • A real query returning results from that content.
  • Optionally, your knowledge deployed, for example as a website widget or a Slack bot.

Before you start​

You need:

  • A Kapa account.
  • Permission to edit your project's sources and integrations.
  • A coding agent: Claude Code, Codex, Cursor, Gemini CLI or opencode.
  • Access to the source you want to ingest, such as a Confluence token.

Most of the supported data sources can be set up this way, including web crawling, GitHub, Zendesk, Confluence, Jira, Notion, Slack, Discord, Google Drive and S3. Set up the rest in the dashboard.

Install the Kapa plugin​

Inside Claude Code:

/plugin marketplace add kapa-ai/kapa-plugin
/plugin install kapa@kapa

Or from your terminal:

claude plugin marketplace add kapa-ai/kapa-plugin
claude plugin install kapa@kapa

Paste the onboarding prompt into your coding agent​

Kapa setup prompt (copy and paste)
Set up my Kapa project using the kapa MCP server.

Kapa is an ingestion and retrieval system for unstructured knowledge. I
connect knowledge sources, Kapa ingests them into one knowledge base and keeps
it in sync, and agents retrieve from it through Kapa's MCP server or retrieval
API. For common use cases Kapa also has prebuilt agents, such as a website
widget or a Slack bot.

## 1. Check you are signed in

Call `list_projects`. It takes no arguments and acts as me, with my real
permissions.

If it fails with an authentication error, tell me to sign in to the kapa
server again (in Claude Code that is `/mcp`, other clients prompt for it or
offer a reconnect), then wait for me to confirm before retrying. There is no API
key to find: no tool takes a Kapa credential as an argument.

If it returns more than one project, ask me which to use. Keep its id.

## 2. Ask what I want to ingest

Ask me, do not pick for me. Kapa can ingest a documentation website, a GitHub
repository, a knowledge base (Zendesk Help Center, Confluence, Notion), a
support history (Zendesk tickets, Jira, Jira Service Management), a community
(Slack, Discord, Discourse), reference material (an OpenAPI spec, a YouTube
channel, Google Drive, files in S3), or question and answer pairs I write myself.

Most projects start with a documentation site. Suggest that if I am unsure.

## 3. Use the skill for what I choose

Each skill carries the exact call order, the fields that matter and the things
that commonly go wrong:

| I want to ingest | Skill |
| :-- | :-- |
| A documentation website | kapa-setup-web-crawl |
| GitHub docs or code files | kapa-setup-github-files |
| GitHub issues | kapa-setup-github-issues |
| GitHub discussions | kapa-setup-github-discussions |
| GitHub pull requests | kapa-setup-github-pull-requests |
| Zendesk Help Center | kapa-setup-zendesk-helpcenter |
| Zendesk tickets | kapa-setup-zendesk-tickets |
| Confluence | kapa-setup-confluence |
| Jira | kapa-setup-jira |
| Jira Service Management | kapa-setup-jira-service-management |
| Notion | kapa-setup-notion |
| Slack | kapa-setup-slack |
| Discord | kapa-setup-discord |
| Discourse | kapa-setup-discourse |
| An OpenAPI spec | kapa-setup-openapi |
| A YouTube channel | kapa-setup-youtube |
| Google Drive | kapa-setup-google-drive |
| Files in S3 | kapa-setup-s3 |
| Answers I write myself | kapa-setup-custom-qa |

If you cannot load a skill, the tool descriptions carry the same arguments:
every source is `create_*_source` for an id, then a config call telling it what
to ingest. Use `search_kapa_docs` when unsure how a Kapa feature works, rather
than guessing.

## 4. Check it is actually ingesting

For every source except a web crawl, saving the configuration starts the
ingest. There is nothing else to call.

A **web crawl** is the exception: it sits there doing nothing until
`start_crawl` runs. Do not leave it configured but never started.

Either way, ingesting takes time. Call `list_sources` with `project_id` and
show me what the project holds and where each source has got to.

## 5. Prove it answers

Ingesting takes a while, so wait until the source reports content before this.

Ask me a question my content should answer, or suggest one from what was
ingested, and call `search_project_knowledge` with my project id. Show me what
comes back. If the answer is thin or wrong, that usually means the crawl kept
navigation rather than article text, or the filters were too narrow, so say so
rather than declaring success.

## 6. Put it to work

There are two ways to put Kapa in front of people. Ask which I want; more than
one is fine.

**Pre-built integrations** deploy out of the box, with no code:

- A **website widget**, the chat bubble on a documentation site:
  `create_widget_integration`. Pass `enabled_domains` to limit where it can
  be embedded. The embed snippet is on the dashboard's integrations page.
- A **Slack bot**: `create_slack_bot_integration` with my workspace and
  channel ids. Then a workspace admin installs the Kapa Slack app, invites it
  to the channel, and runs `/kapa-enable-channel <integration id>` there. It
  answers nothing until then, and you cannot enable it for me.
- A **Discord bot**, the same shape: `create_discord_bot_integration`, then a
  server administrator adds the Kapa app and sends
  `!kapa_enable_channel <integration id>` in the channel. Ask me for the
  server and channel ids; Discord only shows them once Developer Mode is on,
  under User Settings then Advanced.
- **My own MCP server**, so my agents can query my content:
  `create_mcp_integration`. It is served at `<url_slug>.mcp.kapa.ai`, so ask
  me what slug I want and how callers should authenticate.
- A **support form deflector**, which answers before I file a ticket:
  `create_support_form_deflector_integration`.

**Building on Kapa** means calling the retrieval API yourself and putting your
own experience in front of it. For that, do both of these:

1. `create_api_integration`, which is how my queries show up as their own
   caller in analytics rather than mixed in with my widget's.
2. `create_api_key`. It comes back once, in `private_api_key`, and cannot be
   read again, so show it to me and tell me to store it somewhere safe.

Then show me a call that works:

```bash
curl -X POST "https://api.kapa.ai/query/v1/projects/<project_id>/retrieval/" \
  -H "X-API-KEY: <the key you just created>" \
  -H "Content-Type: application/json" \
  -d '{"query": "a question my content answers", "integration_id": "<id>"}'
```

It answers with the matching chunks and their source URLs, and no generated
text: retrieval returns what my content says and leaves the answering to
whatever I put in front of it. `top_k`, `max_chars` and `use_pruning` are
optional.

Point me at https://docs.kapa.ai/api/reference/query-v-1-projects-chat for the chat endpoint if
I want generated answers rather than chunks.

## Rules

- **Credentials are mine.** Ask me for every token and key. Never invent one,
  never reuse one across sources.
- **Ingesting spends my quota.** Confirm with me before `start_crawl`.
- **Preview before ingesting.** For a web crawl, check the extracted text on a
  few pages first. The skill explains how.
- **Ask what to ingest, do not decide it.** Show me which projects, spaces,
  labels or channels a source can read and let me pick. Taking everything is a
  valid choice, so do not filter on my behalf without saying so.
- **When a source ingests nothing**, it is usually a permission I have not
  granted yet, not a config error.

Answer the agent's questions​

From here, the agent leads, and you answer. This section walks through what it asks at each stage, so you know what to have ready.

Sign in to the MCP server​

The agent first checks that you are signed in to the Kapa platform MCP server, so it can reach the platform on your behalf. If you are not, it tells you how to sign in. If you have more than one project, it asks which one to set up.

Choose what to ingest​

Next, the agent lists what Kapa can ingest and asks what you want to start with. Reply with the source, like the URL of your documentation site.

The agent listing the source types Kapa can ingest and asking which one to start with

Wait for your source to ingest​

The agent then works out the source's configuration with you, such as which pages to crawl, and starts ingesting once you give it the go-ahead. Ingestion usually takes a couple of minutes.

To follow its progress, ask the agent for the status of your source, including how many items are already deployed. Or open app.kapa.ai and navigate to Sources (under Configure in the sidebar): the source row shows the deployed count ticking up, and the spinner disappears once ingestion is finished.

Source row showing the deployed page count with a spinner while some updates are still being deployed

Test your index with a few queries​

Next, you test searching the source you just indexed. The agent asks you for a question your content should answer, or suggests one, and shows you the chunks that come back and the source of each one. Ask a few more questions to check other parts of your content.

The platform MCP server lets your agent search with the same retrieval tool that the hosted MCP server and the HTTP API expose, which are how you usually query your index in production.

If the results are thin or wrong, the agent says so rather than declaring success, and points to the likely cause, usually a misconfigured source.

Deploy your index (optional)​

Finally, the agent asks whether you want to deploy your index. Deploying connects it to the places where it gets used: either a Prebuilt Agent, such as a website widget or a Slack bot, that answers your users directly, or a way for your own agents to query it, through a hosted MCP server or the HTTP API. You can pick more than one.

The agent asking how to deploy the project, with options for a website widget, an MCP server, a Slack or Discord bot, and building on the API

Next steps​