Connect a knowledge base to AI agents with MCP (Claude, Cursor…)

AI assistants are only as good as the information they can reach. Out of the box, a general-purpose model knows a lot about the world but nothing about your internal policies, your client files or the niche regulation you have spent years mastering. An MCP knowledge base closes that gap: it exposes a searchable set of documents through the Model Context Protocol, so AI agents (Claude, Cursor, ChatGPT or one you built yourself) can look things up on their own, mid-conversation, and cite what they found. This guide explains how the protocol works, how to connect a knowledge base step by step, and what to watch for in production.

What is MCP (Model Context Protocol)?

The Model Context Protocol is an open standard, introduced in late 2024, that defines how AI applications connect to external tools and data. Think of it as a universal plug: instead of writing a custom integration for every assistant and every data source, you expose your data once as an MCP server, and any MCP client (Claude, Cursor, ChatGPT, a custom agent) can use it. The specification and SDKs are public at modelcontextprotocol.io.

An MCP server can expose three kinds of things: tools (functions the model can call, such as search this base), resources (data the client can read) and prompts (reusable templates). For a knowledge base, tools are what matter: the model decides when it needs information, calls a search or ask tool with a question, and receives text it can reason over.

Why connect a knowledge base to your AI agents with MCP?

You could paste documents into a chat, or upload them to a project. That works for a handful of files and one person. An MCP knowledge base scales differently:

• The model fetches only what it needs. Instead of loading hundreds of pages into the context, it retrieves a few relevant passages per question, which keeps answers focused and costs predictable.
• One source of truth, many clients. The same base serves your assistants (Claude, Cursor…), your internal agents and your scripts. Update a document once and every client sees it.
• Answers are grounded and cited. Retrieval returns specific excerpts, so the assistant can quote its sources instead of paraphrasing from memory.
• Agents become autonomous. In a multi-step workflow, an agent can check a policy, a contract clause or a procedure without a human copying and pasting anything.

Under the hood, the MCP server is simply the front door of a RAG system. If you want to know what happens behind that door, read our explainer on how a RAG pipeline works, or start with the basics in what is RAG.

How an MCP knowledge base works, step by step

1. The client connects to the MCP server and asks which tools are available. The server answers with names, descriptions and input schemas.
2. The user asks something. The model reads the tool descriptions and decides a lookup would help.
3. The model calls a tool, for example with a question string and the target base.
4. The server runs retrieval on the indexed documents and returns either a written answer with citations or the raw relevant passages.
5. The model uses that result to answer the user, and may call the tool again with a refined question.

Answer mode vs passages mode: which one should your agent use?

A knowledge base can return two kinds of results. In answer mode, the server writes a finished answer with numbered citations. In passages mode, it returns the relevant excerpts and lets the calling model do the synthesis. Both are useful; the choice depends on who does the reasoning.

A good rule of thumb: if the agent will merge information from several bases or tools, or must follow its own output format, ask for passages. If you just need a reliable, sourced answer, answer mode is simpler.

How to connect a Kopik knowledge base to your MCP client

Kopik is the library of expert knowledge bases for AI, and every base can be queried over MCP. Here is the full setup.

1. Pick or create a base

Browse the public catalogue for a base on your topic, or create your own from PDFs (with a text layer), Word files or text formats. Our guide on building a knowledge base from your documents covers that part in detail.

2. Create an API key

In your dashboard, create an API key. It starts with kpk_ and is sent as a Bearer token: Authorization: Bearer kpk_… The same key works for the REST API and the MCP server. Treat it like a password. Only list_bases, which browses the public catalogue, works without a key.

3. Choose your MCP endpoint

The general endpoint suits exploratory agents: list_bases lets the model discover what exists, then ask_base returns a written answer with citations and search_base returns passages. The per-base endpoint is better when an assistant should stick to one domain, since the model doesn't have to pick a base at all. Both endpoints use the Streamable HTTP transport, and a client can send up to 10 requests in a single batch.

4. Add the server to your MCP client

Each client has its own settings screen or configuration file, but the information is always the same: the server URL, the HTTP transport, and the Authorization header with your key. In Claude Code, for example, one command registers a base: claude mcp add --transport http kopik-<slug> "https://kopik.io/api/mcp?base=<slug>" --header "Authorization: Bearer kpk_…". Keep the quotes around the URL: without them, shells such as zsh try to expand the ? and the command fails. Cursor and many other clients read a JSON configuration instead, with an entry such as {"mcpServers": {"kopik": {"url": "https://kopik.io/api/mcp", "headers": {"Authorization": "Bearer kpk_…"}}}}. Agent frameworks accept the same URL and header in their own format. Check your client's documentation for the exact syntax, and our developer documentation for the Kopik side.

5. Test with a real question

Ask your assistant something the base should know, and check that it calls the tool, that citations point to the right passages, and that it admits when the base has nothing on the topic. On Kopik, questions that find nothing are neither billed nor counted.

Security and cost considerations

Connecting a model to external tools means giving it the ability to act on your behalf, so a few precautions apply.

• Keep keys out of shared files. Store API keys in environment variables or your client's secret storage, not in a config committed to a repository. Revoke and recreate a key if it leaks.
• Choose visibility deliberately. On Kopik a base is public (listed in the catalogue), unlisted (reachable by link only) or private (owner only). Sensitive internal documents belong in a private base, which you can query for free with your own key (fair-use limit of 200 questions a day): in effect, your own private RAG, with no infrastructure to run. We explain that setup in using a private knowledge base as a RAG backend for your AI agents.
• Keep agents focused. A per-base endpoint pre-targets the tools to a single base, which makes behavior easier to predict.
• Understand the billing. On Kopik, agents and apps pay per request, from prepaid credit, at the price shown on each base and set by its creator, from a few cents. Credit is topped up in packs of €10 to €100 and never expires. The website chat works differently: signed-in users with a verified email get 2 free questions per month, then a monthly subscription with no commitment opens the chat for every base in the library. Neither applies to MCP or the API.
• Set a price ceiling. ask_base and search_base accept an optional maxPriceCents argument, in euro cents. If the base costs more than that, the call is refused and nothing is charged: a useful safeguard for an agent running in a loop, should a creator raise the price.
• Plan for rate limits. Each user can ask up to 20 questions per minute and 1,000 per day. Beyond that, calls are refused with a rate_limited error (and too many requests from one IP address, over 120 a minute, get an HTTP 429 with Retry-After: 60): have your agent wait and retry rather than hammer the server.
• Treat retrieved text as data. Documents from third parties could contain instructions aimed at the model. Kopik returns everything that comes from a base (answers, passages, catalogue descriptions) inside <kopik-untrusted> tags, with a note telling the agent to treat it as reference data, never as instructions. It is a guard against prompt injection, and well-designed agents respect that boundary.

Use cases for an MCP knowledge base

The last row is worth a closer look: because agents pay per request, a well-structured base becomes a product its creator is paid for. We cover that model in how to share your expertise as a knowledge base. Whatever the use case, answer quality depends first on the documents, so read our advice on preparing documents for AI before you upload.

Troubleshooting checklist

• The client shows no tools: check the URL, the transport (HTTP) and the Authorization header format.
• Authentication errors: make sure the key starts with kpk_, is active, and is sent as Bearer.
• The model never calls the tool: mention the base explicitly in your prompt, or use the per-base endpoint.
• Answers say nothing was found: the documents may not cover the topic, or were scanned PDFs without a text layer.
• Answers are too generic: try passages mode and let your agent synthesize with its own instructions.
• zsh answers no matches found: put the server URL in quotes, because of the ? in it.
• A call is refused over the price: the base costs more than the maxPriceCents you set. Raise the ceiling or pick another base.
• Too many requests: you have hit the limit of 20 questions per minute or 1,000 per day. Wait a minute (or the delay given by Retry-After, when present) before retrying.