New: Ask reason for a cited answer
Context Repo

How MCP Servers Connect AI Agents to Knowledge Bases

A grounded look at the Model Context Protocol, what an MCP server does, and what clients need to connect to Context Repo's 29-tool hosted server.

Context Repo Team

13 min read

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. Save a prompt to Context Repo from Cursor. Retrieve it from Claude on a later read. No manual export between those clients.

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 hosted MCP server with 29 tools. We will walk through what that means in practice.

What is the Model Context Protocol?

MCP is a shared language for clients and servers. The ecosystem is large and growing, but transport and authentication support varies. A Context Repo client must support authenticated Streamable HTTP or be able to launch the local stdio bridge. Anthropic introduced MCP, and the official spec is open.

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, such as an OpenAPI specification.
  • Prompts. Server-provided templates the host can present to the user.
  • Sampling. A way for a server to ask the host to run a model call on its behalf.

Context Repo's Streamable HTTP route implements behavior introduced in the 2025-03-26 MCP revision and later. Client and server negotiate a supported protocol version during initialize; matching the protocol is necessary, while authentication and each tool's own input contract still apply.

A few things MCP deliberately does not do:

  • It does not define the database. Each server picks its own storage.
  • It does not choose your identity provider. Remote MCP authorization supports OAuth discovery, while server-specific alternatives such as Context Repo API keys remain implementation choices.
  • It does not decide what tools should exist. That is the server author's job.
  • It does not require the server to run the host model. The host controls its model and tool-calling loop.

The protocol does not require the MCP server to run the host model. The host runs its model and decides when to call which tool, while the server exposes capabilities. A server can still expose model-backed tools. Context Repo's reason tool, for example, invokes a separate server-managed synthesis call after retrieval.

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, can serve resources, and may handle authentication when its transport and deployment require it. The protocol does not care what the server is for, only that it speaks the language.

Context Repo's hosted MCP server is at https://contextrepo.com/mcp. Once an AI client connects, it can reach the prompts, documents, and collections allowed by that connection's credential.

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. Clients that request text/event-stream receive SSE-framed JSON-RPC responses. JSON-only clients receive an unframed response through the server's compatibility adapter.

The 29 hosted tools group into seven 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 App compatibility. search and fetch implement the OpenAI Apps SDK Company Knowledge contract. They are served by the same REST endpoints that power catalog search and per-item reads.
  • Cited reasoning. reason gathers bounded document evidence and returns a best-effort synthesized answer with citations and non-exhaustive limitations. Disagreements appear as ordinary cited statements in the answer. An empty gaps array does not prove complete coverage.

Every tool ships with annotations the host can use when reasoning about a call:

  • A readOnlyHint flag (true for reads, false for writes).
  • A destructiveHint flag (true only on deletes).
  • An idempotentHint flag indicating whether repeating the same call is intended to have the same effect.
  • An openWorldHint flag, which is false for these repository-bound tools.

These are hints, not execution guarantees. They let a host distinguish reads, creates, repeatable updates, and destructive deletes before deciding whether to retry or ask for confirmation.

Resources, briefly

The MCP resource surface has one always-on resource and one conditional resource:

  • 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.
  • ui://search-results is registered only when the MCP Apps feature flag is enabled. It supplies the optional search-results interface described below.

There is no user-profile resource. Authenticated identity and permissions are exposed by the get_user_info tool.

MCP Apps: clickable results, not raw JSON

When the server's MCP Apps feature flag is enabled, Apps-aware hosts can render the ui://search-results HTML resource alongside find_items output. The optional panel shows cards for returned items. Without that feature, find_items still returns its normal text and structured results.

The resource is an HTML document with light and dark color-scheme support. The host, not the tool call itself, decides whether to render the interface.

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 automatic tool discovery, hosted OAuth or API-key authentication, 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. It reaches the same stored data through explicit /v1 endpoints, with REST-specific request shapes, pagination, and response envelopes.

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 methods authenticate the same Context Repo account. OAuth carries the interactive user's authority. API-key access remains limited to the prompt or document scopes granted to that key.

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

This is the right choice when the client supports remote MCP OAuth, such as Claude.ai or ChatGPT. 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:

An MCP host uses the MCP protected-resource metadata and authorization-server metadata during its connection flow. REST clients use the separate /v1 protected-resource document.

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 from prompts.read, prompts.write, documents.read, and documents.write, and send it as Authorization: API-Key gm_... on every request. Collection operations share the document scopes.

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 choose authentication. OAuth-capable remote clients can authorize interactively. For a stdio or API-key client, open contextrepo.com/dashboard and generate a key with the scopes you need, such as prompts.read and documents.read. Collections share the document scopes. Keys start with gm_.
  2. Pick your client. Visit contextrepo.com/mcp-server and pick Cursor (one-click deeplink), Claude Desktop (JSON config instructions), 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. List the available MCP tools. A remote client connected to https://contextrepo.com/mcp and a context-repo-mcp v3 stdio install both discover the current 29 hosted tools, including search_prompts, read_prompt, create_prompt, find_items, deep_search, deep_read, and deep_expand.
  5. Make your first call. Ask the client to use find_items for something you have already saved. The server returns grouped item matches with type-specific IDs. Semantic mode includes scores, and snippets appear only when available. Apps-aware hosts may render the optional search-results UI when that server feature is enabled.

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.
  • Response framing follows the client's Accept header. Streamable-HTTP clients can request SSE-framed JSON-RPC. A compatibility adapter unframes the response for JSON-only clients.
  • Rate limits apply to MCP tool calls. The underlying REST operations use the same per-authenticated-user Upstash sliding windows: 100 API-family calls per minute, 120 read-only calls per minute, and 10 scrapes per minute. Rate-limit failures return through MCP tool-error semantics rather than a normal REST response envelope.
  • The npm package context-repo-mcp is a network-dependent v3 stdio bridge for hosts that prefer a subprocess. It forwards JSON-RPC to the hosted MCP endpoint, so it discovers the same tools and relays the same hosted result contract without package-local business logic.

Why this matters

For Context Repo, the MCP server is what lets a prompt saved in the dashboard appear in Cursor on its next read, with no custom integration 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.

Updated

Your questions, answered.

  • MCP is an open standard from Anthropic that lets AI clients discover tools, read resources, and retrieve server-provided prompts. It is the shared language between your AI tools and the services they connect to.

More articles