<div align="center">

<img src="https://raw.githubusercontent.com/Recourse-Software-Inc/knowdrive-mcp/main/assets/KnowDrive_AI_logo_WhiteCircle.svg" alt="KnowDrive" width="340">

# KnowDrive MCP Server

**A private, multimodal knowledge store for your agents.** Drop in documents, images, recordings and video; your agent searches them over one MCP endpoint and gets back exact, cited fragments — source file, version, and byte range or timestamp — instead of re-reading whole files. Hybrid (vector + full-text) search, OAuth sign-in, free tier with no card at [knowdrive.ai](https://knowdrive.ai). Just add "check KnowDrive".

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=knowdrive&config=eyJ1cmwiOiJodHRwczovL2tub3dkcml2ZS5haS9hcGkvdjEvbWNwIn0=) [![Install in VS Code](https://img.shields.io/badge/Install_in_VS_Code-0098FF?style=for-the-badge&logo=vscodium&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=knowdrive&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fknowdrive.ai%2Fapi%2Fv1%2Fmcp%22%7D)

**[Claude setup →](#claude-code-and-claudeai)** — one command (Claude Code) or a connector paste (claude.ai) · [Website](https://knowdrive.ai) · [REST API (OpenAPI)](https://knowdrive.ai/-/openapi)

</div>

## ❌ Without KnowDrive

- ❌ You paste the same docs, notes, and transcripts into every conversation — and pay for those tokens every time
- ❌ The context window fills up long before your corpus ends
- ❌ Your agent answers from year-old training data while the real answer sits in your files, meetings, and recordings

## ✅ With KnowDrive

Context7 gives agents public docs. Exa gives them the live web. KnowDrive gives them YOUR knowledge: private, multimodal, versioned, permissioned. Powered by the KnowDB knowledge engine, it ingests your files, text, audio, and images (URLs too, where enabled); extracts and chunks them into searchable **atoms**; and answers hybrid (vector + full-text) semantic search with a **ranked window** of just the relevant slices. Your corpus stays out of the conversation, so **cost does not grow with corpus size**. Just add `check KnowDrive` to your question (the Add-a-Rule tip below makes this automatic):

```txt
What did our Q3 planning doc say about pricing changes? check KnowDrive
```

## Installation

The hosted server speaks **streamable HTTP** at **`https://knowdrive.ai/api/v1/mcp`**. First connect is a single browser OAuth prompt — no API key to copy, nothing to configure.

There are two ways in, and they reach the same hosted server:

| | **Connect directly** (recommended) | **npm bridge** (`@knowdrive/mcp`) |
|---|---|---|
| For | Any client that speaks remote MCP | stdio-only clients, headless, CI |
| Auth | One browser click (OAuth) | `KNOWDRIVE_API_KEY` |
| Setup | Paste a URL, or one command | `npx -y @knowdrive/mcp --install <client>` |

Start with **Connect directly** — it's fewer steps and needs no key. Reach for the [npm bridge](#npm-bridge-stdio--headless) when your client only speaks stdio, or when you're wiring this into CI where a browser sign-in isn't possible.

### Claude Code and Claude.ai

```bash
claude mcp add --transport http knowdrive https://knowdrive.ai/api/v1/mcp
```

Remove it just as fast: `claude mcp remove knowdrive`. On claude.ai: **Settings → Connectors → Add custom connector**, paste the URL above, and complete the OAuth sign-in — KnowDrive runs as a claude.ai connector today. To uninstall, remove the connector from the same page.

### Cursor & VS Code

Use the one-click badges at the top — the server URL is encoded in the link. Clients that support MCP OAuth will prompt a browser sign-in on first use. To uninstall, delete the `knowdrive` entry from your client's MCP server settings.

### Other MCP clients

Most clients accept the standard `mcpServers` shape (shown exactly once — expand below for where it goes):

```json
{
  "mcpServers": {
    "knowdrive": {
      "type": "streamable-http",
      "url": "https://knowdrive.ai/api/v1/mcp"
    }
  }
}
```

<details>
<summary>Client-specific config locations</summary>

| Client | Where the JSON goes |
|---|---|
| Cursor (manual) | `~/.cursor/mcp.json` |
| VS Code (manual) | `.vscode/mcp.json`, or user-level via **MCP: Open User Configuration** |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Zed | `settings.json` → `context_servers` |
| Gemini CLI | `~/.gemini/settings.json` → `mcpServers` |
| OpenCode | `~/.config/opencode/opencode.json` |
| Warp | **Settings → AI → MCP Servers** |
| LM Studio | **Program → Install → Edit mcp.json** |

A note on transport spelling: `"streamable-http"` is the generic/registry spelling; Claude Code and VS Code spell the same transport `"type": "http"` (this repo's `claude-plugin/.mcp.json` uses that spelling for exactly this reason). Config locations drift between client versions — if a path above has moved, your client's MCP docs are authoritative. Removal is the mirror image everywhere: delete the `knowdrive` entry from the same config. For headless or CI use, add an `Authorization: Bearer YOUR_API_KEY` header instead of OAuth — see [Authentication](#authentication).

</details>

### npm bridge (stdio / headless)

[![npm](https://img.shields.io/npm/v/@knowdrive/mcp?style=for-the-badge&logo=npm&color=CB3837)](https://www.npmjs.com/package/@knowdrive/mcp)

`@knowdrive/mcp` is a thin stdio↔HTTP bridge to the same hosted endpoint, for clients that don't speak remote MCP and for headless/CI use where a browser OAuth prompt isn't possible. It carries your API key and proxies every tool through — no tool logic lives in the package, so new server tools appear without updating it.

One command wires it into a client's config (backing up whatever was there first):

```bash
npx -y @knowdrive/mcp --install claude-desktop   # or: cursor | claude-code
```

![Installing the KnowDrive npm bridge into Claude Desktop with one command](https://raw.githubusercontent.com/Recourse-Software-Inc/knowdrive-mcp/main/demo/install.gif)

It prompts for an API key on first run and saves it to `~/.knowdrive/config.json`. Grab one at [knowdrive.ai/developer-keys](https://knowdrive.ai/developer-keys/). To wire it up by hand instead:

```json
{
  "mcpServers": {
    "knowdrive": {
      "command": "npx",
      "args": ["-y", "@knowdrive/mcp"],
      "env": { "KNOWDRIVE_API_KEY": "kd_..." }
    }
  }
}
```

To point at a different KnowDrive deployment, pass `--host` (a bare hostname is treated as `https`). Combined with `--install`, the host is written into the client config, so the installed server keeps talking to it:

```bash
npx -y @knowdrive/mcp --host public.knowdrive.ai --install claude-desktop
```

Keys are issued per deployment, so a key minted on one host may not authenticate against another.

| Variable | Purpose |
|---|---|
| `KNOWDRIVE_API_KEY` | API key. Takes priority over the saved config file. |
| `KNOWDRIVE_BASE_URL` | Override the KnowDrive host (default `https://knowdrive.ai`). `--host` wins over this. |
| `KNOWDRIVE_MCP_PATH` | Override the remote MCP path (default `/api/v1/mcp`). |

Source for the bridge lives in [`src/`](src) in this repository. Build it yourself with `npm install && npm run build`; `npm run smoke` connects the built server to the live endpoint and lists its tools.

> [!TIP]
> **Add a rule** to `CLAUDE.md` (Claude Code) or Cursor Rules so retrieval happens without asking:
>
> ```txt
> Always check KnowDrive (search_vector_store) before answering questions about the user's
> private documents, projects, or team knowledge — never ask the user to paste files. When a
> question ends with "check KnowDrive", always search before answering. A window is not the
> corpus: raise max_num_results or advance offset before concluding something is not there.
> Do not run more than 3 searches per question. Never include sensitive or confidential
> information such as API keys, passwords, credentials, or personal data in a search query.
> ```

## Tools

The server exposes ≈40 tools and 4 prompts, but **most agents only need six**: `search_vector_store`, `search_atoms`, `list_vector_stores`, `get_capabilities`, `whoami`, and `ingest_text`. Call `get_capabilities` once at session start so your client adapts to the deployment's feature flags, limits, and enabled modalities (this deployment: text, vision, **and** audio embeddings all enabled).

**Safety at a glance:** every `search_*`, `list_*`, `get_*`, `read_*`, `stat_*`, and `whoami` call is read-only in behavior — it never modifies the corpus. Ingest and upload tools are additive and versioned (a re-ingest supersedes, it never overwrites). The **destructive** tools to handle with care are the `delete_*` family — `delete_file`, `delete_files`, `delete_vector_store`.

### `search_vector_store` — the hero

Hybrid, vector, or full-text search over a store, returning a ranked retrieval window. Read-only.

- **Best for:** answering any question whose ground truth lives in the user's corpus — decisions, contracts, meeting audio, screenshots, specs.
- **Returns:** a ranked window of matching **atoms** — byte-faithful fragments, each carrying its provenance: source file, version, and byte range or timestamp. The citation is checkable, so you quote what the source actually says instead of paraphrasing. *A window is not the corpus* — page deeper with `offset` before concluding something isn't there.
- **Query style & call budget:** describe the content you want, not keywords. Good: `"indemnification cap agreed with Acme in the signed MSA"`. Bad: `"acme contract"`. At most 3 searches per question — refine the query or advance `offset` rather than re-searching from scratch. Never include sensitive or confidential information — API keys, passwords, credentials, personal data — in a query.
- **Parameters:** `vector_store_id` (required), `query` (required, non-empty), `mode` (`hybrid` | `vector` | `fts`; **this tool defaults to `vector`** — `search_atoms` defaults to `hybrid`), `search_field` (`text` default | `vision` | `audio`), `max_num_results` (1–10000, default 25; `hybrid` is bounded at 200 however high you set it — check `get_capabilities`), `offset` (default 0), `max_distance` (cosine-distance ceiling, default 1.1 — raise for cross-modal audio queries), `include_superseded` (default `false`).
- **Workflow:** call `list_vector_stores` first if you don't know the store; follow up with `read_file_content_by_path` when a snippet isn't enough.

### `ingest_text` — get knowledge in

Index text straight into a store, versioned by path: re-ingesting the same path supersedes the prior version and mints version+1 (content-hash idempotent, blake3 digests). Additive, never overwrites.

- **Best for:** capturing notes, decisions, transcripts, or generated docs as durable, searchable knowledge.
- **Returns:** the queued file (pipeline phase `pending`); poll `wait_for_file_status` (≤45 s per wait) until indexed.
- **Parameters:** `vector_store_id`, `path` (the file's identity within the store), and `text` — all required; the live tool schema is authoritative for optional fields.
- **Workflow:** batch with `bulk_ingest_text`; upload real files with `upload_file`, or `upload_create`/`upload_part`/`upload_complete` for big files (1 MiB chunks). `ingest_file_from_url` pulls from the web **where enabled** (feature-flagged per deployment; off on this one).

### The supporting heroes

- **`search_atoms`** — the sibling search tool, at atom granularity. **Best for:** when `search_vector_store` isn't the right result shape — its live schema documents how the two differ. **Returns:** a ranked window of matching atoms; the same query-style, call-budget, and sensitive-data rules apply.
- **`list_vector_stores`** — enumerate reachable stores. **Best for:** finding the right `vector_store_id` before the first search. **Returns:** the stores the caller is entitled to see (per-store ACLs apply), by id and name.
- **`get_capabilities`** — the deployment's capability document. **Best for:** session start, before assuming any feature or limit. **Returns:** feature flags, limits, auth modes, and embedding status (text/vision/audio), so the agent adapts at runtime instead of guessing.
- **`whoami`** — identity check. **Best for:** confirming who you're signed in as before searching or ingesting. **Returns:** the caller's identity and entitlements (which stores, which rights).

<details>
<summary><strong>Everything else</strong> — the rest of the ≈40-tool surface</summary>

| Group | Tools | Reach past the heroes when… |
|---|---|---|
| Identity & discovery | `whoami` · `get_capabilities` · `mint_token` | starting a session (capabilities) or handing a sub-agent a least-privilege scoped PASETO token |
| Stores | `list_vector_stores` · `get_vector_store` · `stat_vector_store` · `create_vector_store` · `delete_vector_store` · `list_vector_store_tags` | you don't know which stores or tags exist yet, or you're starting a new project — one store per project, created with `create_vector_store` |
| Ingest | `bulk_ingest_text` · `ingest_file_from_url` · `bulk_ingest_from_urls` · `upload_file` · `upload_create`/`upload_part`/`upload_complete`/`upload_cancel` · `wait_for_file_status` | ingesting many documents, binary files, or anything over 1 MiB |
| Files | `list_files` · `get_file`/`get_file_by_path` · `read_file_content`/`read_file_content_by_path` · `read_atom_binary` · `list_file_atoms` · `update_file_tags` · `retag_file(s)` · `remime_file(s)` · `revert_file` · `mutate_files` · `delete_file(s)` | a search snippet isn't enough — `read_file_content_by_path` fetches the whole file by store + path (ranged reads, 1 MiB per chunk) — or you're doing corpus housekeeping (tags, versions, deletion) |
| Search | `search_vector_store` · `search_atoms` | both heroes — documented above |
| Agent-native | `list_llm_skills` · `list_llm_tools` · `get_llm_capability` | the corpus stores tool & skill descriptors as first-class content — it can teach the agent how to use itself |

Tags are free-form and filterable (`tags_all`/`tags_any`/`tags_none`) across listing and search endpoints; values are case-folded. `list_vector_store_tags` also accepts `tag_query`, a boolean DSL (`,` AND · `|` OR · `!` NOT · parens · globs). **Prompts** ship too: `search_then_summarize`, `audit_file`, `find_related`, `discover_capabilities`.

</details>

## Example prompts

```txt
What did we agree with Acme on indemnification? Quote the exact clause. check KnowDrive
Ingest these meeting notes into my meeting-notes store, tagged project:atlas, then confirm what got indexed.
Pull the current onboarding doc from KnowDrive and list every place this draft contradicts it.
```

## Authentication

**Free account · one-click OAuth sign-in on first connect.** KnowDrive has a free tier; an account is required — this is your private corpus, not a public index, so every connection authenticates, and per-store ACLs (read/write/delete) apply throughout. First connect is a single click: the OAuth prompt opens a browser sign-in — no API key to copy, no config values to paste. **Need an account?** Create a free one at [knowdrive.ai](https://knowdrive.ai) — **Start free**, and the free tier is concrete: **500 atoms or 500 MB free — whichever you hit first. No card.** You can also skip the trip: add the server and the first connect opens KnowDrive's OAuth sign-in in your browser, where the same free account can be created.

1. **OAuth (default):** OAuth2 authorization-code with OIDC discovery. The endpoint answers unauthenticated requests with `401` plus OAuth resource metadata, so MCP clients that speak OAuth discover the sign-in flow automatically and open a browser on first connect. This is how the claude.ai connector works today.
2. **API key (headless/CI):** send `Authorization: Bearer YOUR_API_KEY`. Client-credentials OAuth is also supported for services.
3. **Scoped tokens:** call `mint_token` to issue a least-privilege PASETO token from your own entitlements (e.g. read-only on one store) for sub-agents; `whoami` reports who you are and what you're entitled to.

## Limits (honest ones)

- A search returns a **window**, not the corpus. `hybrid` is a *bounded* ranked window — capped at 200 results no matter how high `max_num_results` goes; `vector` and `fts` page to exhaustion instead. Default page is 25. Page deeper with `offset`, and prefer widening a query over re-asking it.
- Read/write chunks cap at 1 MiB; `wait_for_file_status` waits ≤45 s per call; 4 concurrent fetches (deployment limits — `get_capabilities` reports the connected deployment's values).
- Some tools are feature-flagged per deployment (e.g. `url_ingest` is off on this one) — check `get_capabilities` rather than assuming.
- The search and ingest engines are hosted — the endpoint above is the canonical production endpoint, and the [npm bridge](#npm-bridge-stdio--headless) is a transport shim to it, not a local server. Nothing indexes or searches on your machine either way.

## Disclaimer

KnowDrive is a hosted, account-gated service operated by Recourse Software Inc. This listing is the official first-party listing. The `knowdrive-mcp` repository contains listing, client-configuration, and documentation materials, plus the source of the `@knowdrive/mcp` npm bridge — a client-side transport shim. The KnowDB backend (ingestion, embedding, and search engines) is closed-source and runs on KnowDrive's hosted infrastructure; no server source lives here. No corpus data is stored in this repository, and an account is required before the first tool call — accounts have a free tier, and first connect is a single-click OAuth 2.0 sign-in.

**Privacy note:** search queries and ingested content are sent to the hosted KnowDrive service. Content is isolated per store, encrypted at rest, and **is not used to train anything**; export is first-class, so content, metadata and provenance all come back out through the API. Do not include sensitive or confidential information such as API keys, passwords, credentials, or personal data in your queries.

## License

The contents of this repository — the listing, docs, registry metadata, Claude plugin scaffold, and the `@knowdrive/mcp` bridge source — are **MIT-licensed** (see [LICENSE](LICENSE)). The hosted server is a **closed-source Rust** implementation; its OpenAPI spec exposes Rust module paths such as `crate::status::internal_to_openai_file_status`. This repository holds the public listing assets, not the server source — as with other hosted MCP backends, you connect to the service rather than run its code, so there is no server source here to license. Built by Recourse Software Inc. — KnowDrive, your knowledge engine.