# Context Repo — Full Agent Context

> Context Repo is the AI Context Repo for agents. Save prompts and
> documents with version history, organize them in collections, and access
> them from ChatGPT, Claude, Cursor, and 90+ MCP-compatible clients via a
> 29-tool MCP server (27 power tools + OpenAI Apps SDK
> search/fetch).

This file inlines a curated, hand-authored, agent-readable knowledge pack.

Other agent surfaces:

- [`/llms.txt`](https://contextrepo.com/llms.txt) — Index file (60–100 lines, llmstxt.org spec)
- [`/openapi.json`](https://contextrepo.com/openapi.json) — OpenAPI 3.1 spec for the 30 REST operations
- [`/api/openapi.yaml`](https://contextrepo.com/api/openapi.yaml) — YAML mirror of the OpenAPI spec
- [`/index.md`](https://contextrepo.com/index.md) — Markdown rendering of the homepage
- [`/pricing.md`](https://contextrepo.com/pricing.md) — Plain markdown pricing reference
- [`/agent`](https://contextrepo.com/agent) — Machine-readable capability catalog (JSON or markdown)
- [`/.well-known/mcp.json`](https://contextrepo.com/.well-known/mcp.json) — MCP discovery (SEP-1649)
- [`/.well-known/agent.json`](https://contextrepo.com/.well-known/agent.json) — OpenAI ai-plugin manifest
- [`/.well-known/agent-card.json`](https://contextrepo.com/.well-known/agent-card.json) — A2A Agent Card
- [`/.well-known/mcp/server-card.json`](https://contextrepo.com/.well-known/mcp/server-card.json) — MCP server card (29 tools)
- [`/.well-known/api-catalog`](https://contextrepo.com/.well-known/api-catalog) — RFC 9727 linkset
- [`/.well-known/oauth-protected-resource/v1`](https://contextrepo.com/.well-known/oauth-protected-resource/v1) — RFC 9728 (REST)
- [`/.well-known/oauth-protected-resource/mcp`](https://contextrepo.com/.well-known/oauth-protected-resource/mcp) — RFC 9728 (MCP)
- [`/.well-known/oauth-authorization-server`](https://contextrepo.com/.well-known/oauth-authorization-server) — RFC 8414

## When To Use Context Repo

Use Context Repo when an agent needs to:

### 1. Retrieve A Versioned Prompt Template

- Pull a stored prompt by id or by semantic search
- Inspect or restore previous versions
- Cross-reference prompt parameters and target model

### 2. Search A User's Own Knowledge Workspace

- Semantic / 1536-dim vector search across prompts, documents, collections
- Literal title/description search when exact-match is required
- Hierarchical "deep search" inside long documents (chunk-level)
- Citation-ready Company-Knowledge results for ChatGPT Apps SDK

### 3. Store New Context From An Agent Workflow

- Create / update prompts and documents (with auto-embedding)
- Add items to collections for later retrieval
- Capture web pages via Firecrawl ingestion
- Process 75+ file formats via LlamaIndex Cloud

### 4. Sync Context Across Clients

- Same workspace visible from Claude, Cursor, ChatGPT, VS Code, Windsurf,
  Factory, Amp, Chrome Extension, and 90+ other MCP-compatible clients
- REST API for non-MCP automation
- Real-time sync via Convex subscriptions in the web dashboard

## When Not To Use Context Repo

- **As a vector-DB substitute for a high-volume RAG pipeline.**
  Context Repo is workspace-scoped; per-user storage is not unbounded.
- **For general web search or live news retrieval.**
  No web crawler or live index — use a search API.
- **For team-wide shared workspaces or org-level RBAC.**
  Workspaces are per-user. Sharing is via JWT/API-key delegation, not
  multi-tenant team accounts.
- **As a conversation history store for an LLM chat client.**
  Use the client's own history; Context Repo stores reusable artifacts.
- **As a CMS for human-rendered content.**
  No WYSIWYG editor; markdown-only document model.
- **For real-time streaming agent telemetry.**
  Mutations are transactional; the platform does not push
  server-initiated events. The MCP transport itself does support
  SSE-framed JSON-RPC responses for clients that opt in via
  `Accept: text/event-stream` — see the [MCP Server](#mcp-server) section
  below.

## Platform At A Glance

- **Built on** — Next.js 15 (App Router, Turbopack) + Convex
  (real-time backend) + Clerk (auth + billing) + TypeScript strict mode
- **License** — Proprietary ([policies](https://contextrepo.com/policies))
- **Status** — Pre-launch SaaS; subscription-gated dashboard
- **Region** — Vercel global edge + Convex serverless
- **Domain** — [contextrepo.com](https://contextrepo.com)
- **Support** — [support@contextrepo.com](mailto:support@contextrepo.com)

### Content Model

- **prompts** — Versioned text templates with optional `${variable}`
  placeholder syntax (clients interpolate at call time). Per-prompt:
  title, description, content, parameters, change-log
  per version.
- **documents** — Markdown / plain-text knowledge artifacts with full
  version history, automatic 1536-dim embeddings, and chunk-level
  "deep search" navigation. Origins: manual, file upload (75+ formats
  via LlamaIndex), web scrape (Firecrawl).
- **collections** — Folders that group prompts and documents,
  optionally colored / iconed. Items can belong to multiple
  collections. Any MCP client can scope its search and reads to a
  single collection.

### Authentication

Clerk handles all user auth. Three Bearer-token shapes are accepted:

- **Session JWT** — logged-in dashboard / extension users
- **`oat_*`** — Clerk OAuth user-delegation token (ChatGPT MCP connector)
- **`mt_*` / `ak_*`** — Clerk M2M / Clerk-managed API key

Plus first-party API key:

- **`gm_<publicId>_<secret>`** — via header `Authorization: API-Key gm_...`

JWT / `oat_` tokens bypass scope gates; `mt_` / `ak_` and `gm_` keys
MUST carry one of the four declared scopes: `prompts.read`,
`prompts.write`, `documents.read`, `documents.write`. The
`documents.write` scope covers `POST /v1/documents/scrape` (there is
no separate scrape scope). `*.write` implies `*.read` within the same
resource.

Auth metadata:

- [`/.well-known/oauth-authorization-server`](https://contextrepo.com/.well-known/oauth-authorization-server) (RFC 8414)
- [`/.well-known/oauth-protected-resource/v1`](https://contextrepo.com/.well-known/oauth-protected-resource/v1) (REST, RFC 9728)
- [`/.well-known/oauth-protected-resource/mcp`](https://contextrepo.com/.well-known/oauth-protected-resource/mcp) (MCP, RFC 9728)

### Rate Limits

Per authenticated user, sliding window:

| Family | Window | Endpoints |
|---|---|---|
| `scrape` | 10 requests / 60 s | `POST /v1/documents/scrape` |
| `api` | 100 requests / 60 s | `POST` / `PATCH` / `DELETE` / `PUT`, search, `pd/*` |
| `readonly` | 120 requests / 60 s | `GET /v1/...`; `pd/read`; `pd/expand` |

Headers on 429 only:

- `X-RateLimit-Limit`
- `X-RateLimit-Remaining`
- `X-RateLimit-Reset` (ISO 8601)
- `Retry-After` (seconds)

Behavior is fail-open if Upstash Redis is unavailable.

## MCP Server

- **Endpoint** — [`https://contextrepo.com/mcp`](https://contextrepo.com/mcp)
- **Transport** — streamable-http (MCP spec rev ≥ 2025-03-26)
- **Streaming: YES** — Clients that advertise `Accept: text/event-stream`
  receive SSE-framed JSON-RPC; JSON-only clients receive a single
  chunked response (an Accept-shim unframes the SSE body before
  delivery, so simpler agents can call `/mcp` without negotiating
  event-stream).
- **Discovery** — [`/.well-known/mcp.json`](https://contextrepo.com/.well-known/mcp.json) (SEP-1649)
- **Server card** — [`/.well-known/mcp/server-card.json`](https://contextrepo.com/.well-known/mcp/server-card.json) (29 tools)
- **Auth** — OAuth 2.1 (Clerk) OR Bearer API key
- **npm package** — [`context-repo-mcp`](https://www.npmjs.com/package/context-repo-mcp)

Run via `npx`:

```bash
npx -y context-repo-mcp
```

Cursor one-click install (deeplink):

```text
cursor://anysphere.cursor-deeplink/mcp/install?name=context-repo&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvbnRleHQtcmVwby1tY3AiXSwiZW52Ijp7IkNPTlRFWFRSRVBPX0FQSV9LRVkiOiIifX0=
```

Claude Desktop / generic MCP config:

```json
{
  "mcpServers": {
    "context-repo": {
      "command": "npx",
      "args": ["-y", "context-repo-mcp"],
      "env": { "CONTEXTREPO_API_KEY": "<gm_...>" }
    }
  }
}
```

### Tool Categories (29 Registrations)

#### User (1)

| Tool | Description |
|---|---|
| `get_user_info` | Authenticated user identity + permissions |

#### Prompts (7)

| Tool | Description |
|---|---|
| `search_prompts` | List / search prompts |
| `read_prompt` | Full prompt body + variables |
| `create_prompt` | New prompt |
| `update_prompt` | Edit (content edit → new version) |
| `delete_prompt` | Delete (irreversible) |
| `get_prompt_versions` | Version history |
| `restore_prompt_version` | Roll back to a past version |

#### Documents (7)

| Tool | Description |
|---|---|
| `list_documents` | Paginated list |
| `get_document` | Full document body |
| `create_document` | New document (auto-embeds) |
| `update_document` | Edit (content edit → new version + re-index) |
| `delete_document` | Delete (irreversible) |
| `get_document_versions` | Version history |
| `restore_document_version` | Roll back |

#### Collections (7)

| Tool | Description |
|---|---|
| `list_collections` | Paginated list |
| `get_collection` | Membership + metadata |
| `create_collection` | New collection |
| `update_collection` | Edit metadata |
| `delete_collection` | Delete (items NOT deleted) |
| `add_to_collection` | Attach items |
| `remove_from_collection` | Detach items |

#### Catalog Search (1)

| Tool | Description |
|---|---|
| `find_items` | Semantic OR literal across prompts / documents / collections |

#### OpenAI Apps SDK Company-Knowledge (2)

| Tool | Description |
|---|---|
| `search` | Flat citation-ready result set |
| `fetch` | Full content of a single id |

#### Deep Search (3)

| Tool | Description |
|---|---|
| `deep_search` | Vector-similarity inside document chunks |
| `deep_read` | Single chunk with hierarchy metadata |
| `deep_expand` | Navigate up / down / next / previous / surrounding from a chunk |

#### Reasoning (1)

| Tool | Description |
|---|---|
| `reason` | Synthesized, cited answer composed across your documents — with citations, gaps, and conflicts (read-only) |

## REST API (30 Operations Under /v1)

- **Spec** — [`/openapi.json`](https://contextrepo.com/openapi.json) (OpenAPI 3.1, JSON)
- **YAML** — [`/api/openapi.yaml`](https://contextrepo.com/api/openapi.yaml)
- **Catalog** — [`/.well-known/api-catalog`](https://contextrepo.com/.well-known/api-catalog) (RFC 9727 linkset)

### Tags

- `prompts`
- `documents`
- `collections`
- `search`
- `progressive-disclosure`
- `user`

### Operations

| Operation | Verb | Path | Success Status |
|---|---|---|---|
| `listCollections` | GET | `/v1/collections` | 200 |
| `createCollection` | POST | `/v1/collections` | 201 + `Location` |
| `getCollection` | GET | `/v1/collections/{id}` | 200 |
| `getCollectionItems` | GET | `/v1/collections/{id}/items` | 200 |
| `updateCollection` | PATCH | `/v1/collections/{id}` | 200 |
| `deleteCollection` | DELETE | `/v1/collections/{id}` | 200 + `{success,id}` |
| `addItemsToCollection` | POST | `/v1/collections/{id}/items` | 200 |
| `removeItemsFromCollection` | PUT | `/v1/collections/{id}/items` | 200 (PUT because DELETE-with-body is non-standard) |
| `listDocuments` | GET | `/v1/documents` | 200 |
| `createDocument` | POST | `/v1/documents` | 201 + `Location` |
| `getDocument` | GET | `/v1/documents/{id}` | 200 |
| `getDocumentVersions` | GET | `/v1/documents/{id}/versions` | 200 |
| `updateDocument` | PATCH | `/v1/documents/{id}` | 200 |
| `deleteDocument` | DELETE | `/v1/documents/{id}` | 200 + `{success,id}` |
| `restoreDocumentVersion` | POST | `/v1/documents/{id}/restore` | 200 |
| `scrapeUrl` | POST | `/v1/documents/scrape` | 202 Accepted |
| `listPrompts` | GET | `/v1/prompts` | 200 |
| `createPrompt` | POST | `/v1/prompts` | 201 + `Location` |
| `getPrompt` | GET | `/v1/prompts/{id}` | 200 |
| `getPromptVersions` | GET | `/v1/prompts/{id}/versions` | 200 |
| `updatePrompt` | PATCH | `/v1/prompts/{id}` | 200 |
| `deletePrompt` | DELETE | `/v1/prompts/{id}` | 200 + `{success,id}` |
| `restorePromptVersion` | POST | `/v1/prompts/{id}/restore` | 200 |
| `search` | GET | `/v1/search` | 200 |
| `pdSearch` | POST | `/v1/pd/search` | 200 |
| `pdExpand` | POST | `/v1/pd/expand` | 200 |
| `pdRead` | GET | `/v1/pd/read/{chunkId}` | 200 |
| `pdCreateSession` | POST | `/v1/pd/session` | 200 |
| `reason` | POST | `/v1/reason` | 200 |
| `getMe` | GET | `/v1/user/me` | 200 |

### Standard Envelopes

Single resource:

```json
{ "data": { } }
```

List resource:

```json
{
  "data": [],
  "pagination": { "cursor": "<opaque>", "hasMore": false }
}
```

Search:

```json
{
  "data": {
    "documents": [],
    "prompts": [],
    "collections": []
  },
  "meta": { "query": "<str>", "semantic": true, "latencyMs": 0 }
}
```

Delete (M-048):

```json
{ "success": true, "id": "<resourceId>" }
```

Error:

```json
{
  "error": {
    "code": 400,
    "message": "<str>",
    "details": null
  }
}
```

### Response Status Codes

| Code | Meaning |
|---|---|
| 200 | Success on GET / PATCH / search / DELETE (M-048) |
| 201 | Resource created |
| 202 | Scrape accepted (async) |
| 400 | Validation / malformed input |
| 401 | Unauthenticated / verification failed |
| 403 | Insufficient permission scope |
| 404 | Not found |
| 413 | Payload too large |
| 429 | Rate limit exceeded (with rate-limit headers) |
| 500 | Internal error fallthrough |

## Examples

Synthetic identifiers (`doc_...`, `prm_...`, `gm_...`) are placeholders.
Send your own IDs and tokens at call time.

### REST — List Documents (Happy Path)

Request:

```http
GET /v1/documents?limit=20 HTTP/1.1
Host: contextrepo.com
Authorization: Bearer <session-jwt-or-oat_token>
Accept: application/json
```

Response (`200 OK`):

```json
{
  "data": [
    {
      "id": "doc_2yA3kQv7nP1xR8sD",
      "title": "Quarterly product strategy",
      "tags": ["strategy", "Q2"],
      "updatedAt": "2026-04-21T14:32:11.000Z"
    }
  ],
  "pagination": {
    "cursor": "eyJpZCI6ImRvY18yeUEza1F2N25QMXhSOHNEIn0=",
    "hasMore": true
  }
}
```

### REST — Create Prompt (201 + Location)

Request:

```http
POST /v1/prompts HTTP/1.1
Host: contextrepo.com
Authorization: API-Key gm_<publicId>_<secret>
Content-Type: application/json

{
  "title": "Summarize meeting transcript",
  "description": "Condense raw transcript into action items",
  "content": "Summarize the following transcript:\n${transcript}"
}
```

Response (`201 Created`):

```http
HTTP/1.1 201 Created
Location: /v1/prompts/prm_8Vb2nY4mZ6pQ9rT1
Content-Type: application/json

{
  "data": {
    "id": "prm_8Vb2nY4mZ6pQ9rT1",
    "title": "Summarize meeting transcript",
    "description": "Condense raw transcript into action items",
    "createdAt": "2026-04-27T09:14:55.000Z"
  }
}
```

### MCP — `find_items` Tool Call

JSON-RPC over the streamable-http transport at `/mcp`.

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "find_items",
    "arguments": {
      "query": "incident response runbook",
      "type": "all",
      "semantic": true,
      "limit": 5
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"results\":[{\"id\":\"doc_2yA3kQv7nP1xR8sD\",\"type\":\"document\",\"title\":\"Incident response runbook v3\",\"score\":0.87,\"highlight\":\"Step 1: page on-call ...\"},{\"id\":\"prm_8Vb2nY4mZ6pQ9rT1\",\"type\":\"prompt\",\"title\":\"Post-incident review template\",\"score\":0.74}]}"
      }
    ]
  }
}
```

## Pricing

7-day free trial on the Pro and Pro Max plans.

| Plan | Monthly | Includes |
|---|---|---|
| **Pro** | $9.99 | ChatGPT App, Claude Desktop MCP, OAuth MCP Server, API key access, prompt / document / collection storage with version history, 75+ file format processing, semantic search, Chrome Extension |
| **Pro Max** | $19.99 | Everything in Pro at 2× storage, web scrapes, and document uploads |
| **Ultimate** | $99.99 | Everything in Pro at 10× storage, web scrapes, and document uploads |

Pricing source-of-truth: Clerk Billing dashboard. Live signup:
[contextrepo.com/pricing](https://contextrepo.com/pricing).

## Integrations (Named, First-Party)

- Claude Desktop (MCP)
- Cursor (MCP, one-click deeplink install)
- ChatGPT (Custom GPT App, OAuth via Clerk)
- VS Code (Copilot, MCP)
- Windsurf (MCP)
- Factory (MCP)
- Amp (MCP)
- Chrome Extension (Firecrawl-based web capture)
- REST API client (Bearer / API-key)
- [`context-repo-mcp`](https://www.npmjs.com/package/context-repo-mcp) npm package (standalone CLI / programmatic)

90+ additional MCP-compatible clients in the broader ecosystem are
protocol-compatible. Concrete compatibility is bounded by support for
the MCP "streamable-http" transport.

## Error Handling Reference

All REST and MCP errors use the same wire format:

```json
{
  "error": {
    "code": 400,
    "message": "Title is required when creating a prompt",
    "details": { "field": "title" }
  }
}
```

Common error scenarios:

- **400** — Missing required field, invalid Convex ID, schema validation
- **401** — Missing `Authorization` header, token verification failed
- **403** — Token / API-key lacks the required scope for this operation
  (writes need `prompts.write` or `documents.write`; scrape is covered
  by `documents.write`)
- **404** — Resource not found OR resource not owned by the authenticated
  user (resources are workspace-scoped; cross-user access is impossible
  and surfaces as 404, not 403)
- **413** — Body too large; field-level cap is 2 MB per content field
- **429** — Rate limit exceeded; consult headers and `Retry-After`
- **500** — Unexpected handler error; transient — retry idempotently if safe

## Design Constraints Agents Should Know

- **Vector dimension: 1536 (text-embedding-3-small).** Mismatched
  embeddings silently fail; agents that supply pre-computed vectors
  must match.
- **Document body cap: 2 MB per content field on the wire**
  (`REST_WIRE_FIELD_CAP_BYTES`). Agents that construct large documents
  should chunk before upload.
- **Prompts store `${variable}` placeholders verbatim.** Interpolation
  is the client's responsibility at call time.
- **Pagination cursors are opaque base64 strings;** do not parse them.
- **Default page size is 20; max is 100.**
- **DELETE returns 200 + `{success,id}`, not 204.** Intentional for
  MCP-client compatibility (M-048).
- **List endpoints return at most 100 items per page;** agents that
  need full enumeration must follow `pagination.cursor` until
  `hasMore=false`.

## Contact

- Email: [support@contextrepo.com](mailto:support@contextrepo.com)
- X: [x.com/contextrepo](https://x.com/contextrepo)
- GitHub: [Gitmaxd/context-repo-mcp](https://github.com/Gitmaxd/context-repo-mcp)
- Docs: [contextrepo.com/docs](https://contextrepo.com/docs)
- Status: [contextrepo.com/status](https://contextrepo.com/status)

Last verified: 2026-05-28