MCP Servers13 min read·

How MCP Servers Connect AI Agents to Knowledge Bases

A grounded look at the Model Context Protocol, what an MCP server actually does, and how Context Repo's 28-tool MCP server connects Claude, Cursor, ChatGPT, and 90+ AI clients to your context repository.

By Context Repo Team

The Model Context Protocol is one of those pieces of plumbing that becomes invisible once it works. You stop thinking about how Claude got access to your prompts, and start thinking about which prompt to use. Write a prompt in Cursor. Use it from Claude two minutes later. No copy-paste, no exporting, no switching tabs.

This article unpacks what is happening underneath. It is written for two readers at once: the prosumer who lives in ChatGPT or Claude and wants to know what they are committing to when they install an MCP server, and the engineer who wants the architecture grounded in real code paths.

Context Repo ships a production MCP server with 28 tools. We will walk through what that means in practice.

What is the Model Context Protocol?

MCP is a shared language. AI clients (Claude Desktop, Cursor, ChatGPT, VS Code, Windsurf, and 90+ others) all learned the same way of asking a remote service "what can you do?" and then calling those capabilities. Anthropic introduced it, the official spec is open, and adoption is now broad across the AI client ecosystem.

When a client connects to an MCP server, the server can offer four things:

  • Tools. Functions the AI can call (for example search_prompts or create_document). Each tool has a typed input shape, a description, and safety hints.
  • Resources. Read-only artifacts the AI can fetch (for example an OpenAPI spec or a user profile).
  • Prompts. Pre-canned templates the host can offer back to the user.
  • Sampling. A way for a server to ask the host to run a model call on its behalf.

The current protocol revision Context Repo aligns with is 2025-03-26. That number is the contract. As long as the client and server agree on it, the rest just works.

A few things MCP deliberately does not do:

  • It does not define the database. Each server picks its own storage.
  • It does not define authentication. Clients and servers agree on OAuth or API keys out of band.
  • It does not decide what tools should exist. That is the server author's job.
  • It does not run the model. The AI client does, and the server just answers calls.

That last point is worth repeating. An MCP server never holds a model. It exposes capabilities. The host runs the model and decides when to call which tool. The split is intentional. It keeps servers small, easy to audit, and stateless.

What is an MCP server?

An MCP server is any process that speaks the MCP protocol over a transport (stdio, SSE, or streamable HTTP, the newer HTTP-based binding). It advertises its tools, optionally serves resources, and handles authentication. The protocol does not care what the server is for, only that it speaks the language.

Context Repo's MCP server is one URL, https://contextrepo.com/mcp. Your AI client connects to that URL once. After that, everything you have saved in your repository (prompts, documents, collections) is reachable from inside the chat.

What does Context Repo's MCP server expose?

Under the hood, the server uses streamable HTTP, the modern way MCP travels over a normal web connection. Older clients that send Accept: text/event-stream still work, because the server detects the request type and adapts on the fly. You do not need to know which transport your client uses. It just works.

The 28 tools group into six clean categories:

  • Prompts (CRUD plus versions). search_prompts, read_prompt, create_prompt, update_prompt, delete_prompt, get_prompt_versions, restore_prompt_version.
  • Documents (CRUD plus versions). list_documents, get_document, create_document, update_document, delete_document, get_document_versions, restore_document_version.
  • Collections (CRUD plus membership). list_collections, get_collection, create_collection, update_collection, delete_collection, add_to_collection, remove_from_collection.
  • Cross-cutting search. find_items (catalog-level search across prompts, documents, and collections in one call), deep_search (passage-level vector search inside documents), deep_read (read a single passage), deep_expand (jump up, down, or sideways through a document's outline).
  • Account. get_user_info.
  • ChatGPT Apps SDK aliases. search and fetch. These are the names ChatGPT's Apps SDK expects, served by the same REST endpoints that power find_items and the per-item reads. Same data, ChatGPT-shaped names.

Every tool ships with safety hints the calling AI can reason about:

  • A readOnlyHint flag (true for reads, false for writes).
  • A destructiveHint flag (true only on deletes).

The pair lets the AI decide whether a call is safe to retry on a network blip, or whether it should ask you first before retrying a delete. Small detail, big difference when an agent is working on its own.

Resources, briefly

Two resources ship today:

  • contextrepo://openapi returns the full OpenAPI 3.1 specification for the REST API. It is intentionally readable without auth, because the same document is already public at /openapi.json. Agents that find us by MCP can pivot straight into the REST contract.
  • A user-info resource scoped to whoever is signed in.

A third resource, ui://search-results, is the bridge to the next section.

MCP Apps: clickable results, not raw JSON

The MCP Apps extension lets a server return interactive HTML widgets the host can render right inside the conversation. When you ask ChatGPT to search your context repository, the result panel shows clickable cards with titles, snippets, and links, not a wall of JSON.

The widget is a real HTML page (<!DOCTYPE html>, <meta name="color-scheme" content="light dark"> for theme awareness, a strict Content-Security-Policy that scopes the frame to the ChatGPT and Claude.ai sandboxes). Safe to render, easy to read, no surprises.

MCP server vs REST API: when do you use which?

Both surfaces talk to the same data. The choice comes down to who is doing the calling.

Use the MCP server when your AI client already speaks MCP (Claude Desktop, Cursor, Claude.ai, ChatGPT via the Apps platform). You get one-click install, automatic tool discovery, OAuth-scoped sharing, and zero glue code on your side.

Use the REST API when you are writing a script, a server-to-server integration, a CI job, or anything that is not an MCP host. Same endpoints, same auth, same data.

The reason MCP exists at all is that without it, every AI client needs a custom integration with every product. Two clients and ten products means twenty integrations to build and maintain. With MCP, each product builds one server, each client speaks the protocol once, and the integration shape collapses.

Rendering diagram…

One server, many clients, one place for your context. Read the companion piece on semantic search and deep search for how retrieval actually works once your AI is connected.

How do AI agents authenticate to a context repository over MCP?

Two ways. Both resolve to the same identity, both access the same content.

OAuth (the same flow you use to connect any modern app)

This is the right choice when the client is an MCP host like Claude Desktop or Cursor. You see a normal Clerk sign-in screen, approve the connection, and the client gets back an access token. We verify the token on every request.

Under the hood it is OAuth 2.1 with PKCE (the modern OAuth flow that lets you log in safely without a shared secret in the URL). Discovery metadata, the public document the client uses to find the right endpoints, lives at:

The MCP host discovers these three documents during its connection handshake. From your side, it looks like a normal sign-in.

Per-user API keys (long-lived, scoped, easy to revoke)

This is the right choice when the calling client is a script, a server-to-server integration, or anywhere you want a long-lived credential without an OAuth flow each time. Generate a key in the dashboard, pick the scopes (prompts.read, documents.write, collections.scrape, and others), and send it as Authorization: API-Key gm_... on every request.

Server-side we verify with bcrypt at rounds=12 (the same one-way hashing standard that protects passwords). The raw key is never stored. If a key leaks, revoke it from the dashboard and generate a new one.

Both modes resolve to the same authenticated user. The full auth surface is documented at /docs/api/authentication.

How to connect Claude, Cursor, or ChatGPT to your context repository

Five steps, a few seconds each.

  1. Sign in and create an API key. Open contextrepo.com/dashboard and generate an API key with the scopes you need (for example prompts.read, documents.read, collections.read). Keys start with gm_.
  2. Pick your client. Visit contextrepo.com/mcp-server and pick Cursor (one-click deeplink), Claude Desktop (one-click install badge), VS Code, Windsurf, Factory, Amp, or OpenAI.
  3. Install the MCP server. For Cursor, click the install badge and Cursor opens with the MCP config pre-populated. For Claude Desktop or other stdio clients, install the npm package context-repo-mcp and add a short JSON config entry with your API key.
  4. Verify tool discovery. From the client, list the available MCP tools. You should see all 28, including search_prompts, read_prompt, create_prompt, find_items, deep_search, deep_read, and deep_expand. The server identifies as mcp-typescript server on vercel v0.1.0.
  5. Make your first call. Ask the client to find_items for something you have already saved. The client routes the call through the MCP server, which returns matching items with titles, IDs, and short highlights rendered as clickable cards.

That is the entire setup. No exporting, no importing, no copy-paste.

Honest notes on the rough edges

A few things worth knowing before you build a workflow on top of this:

  • initialize and tools/list are unauthenticated by design. MCP host discovery probes need to complete without a credential. Mutations and reads of your actual content still require auth.
  • Older MCP clients sometimes only speak SSE. Context Repo's server supports both streamable HTTP and the older SSE path via Accept-header negotiation, so older clients keep working.
  • Rate limits apply to MCP calls. The same Upstash Redis sliding window that paces the REST API also paces MCP. The shared default is 100 requests per minute per API key for writes, 120 per minute for reads. Watch the X-RateLimit-Remaining header if you are driving the server hard from an agent loop.
  • The npm package context-repo-mcp is a thin client wrapper for stdio hosts (Claude Desktop, IDE plugins that prefer subprocess MCP). It proxies stdio JSON-RPC calls to the hosted streamable-HTTP server. The hosted server at https://contextrepo.com/mcp is the source of truth.

Why this matters

For Context Repo, the MCP server is what lets a prompt you wrote in the dashboard appear in your Cursor IDE three minutes later, with no glue code written by you. The integration is structural, not bespoke. We built this for people and agents, not just engineers.

For the broader AI ecosystem, MCP is doing the same thing HTTP did for APIs and OAuth did for sign-in. It collapses the integration surface so the interesting work can move up the stack.