vectros-mcp-server

# @vectros-ai/mcp-server

[![npm](https://img.shields.io/npm/v/@vectros-ai/mcp-server)](https://www.npmjs.com/package/@vectros-ai/mcp-server)
[![license](https://img.shields.io/npm/l/@vectros-ai/mcp-server)](https://www.apache.org/licenses/LICENSE-2.0)

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=vectros&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB2ZWN0cm9zLWFpL21jcC1zZXJ2ZXIiXSwiZW52Ijp7IlZFQ1RST1NfQVBJX0tFWSI6IiJ9fQ%3D%3D)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=vectros&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40vectros-ai%2Fmcp-server%22%5D%2C%22env%22%3A%7B%22VECTROS_API_KEY%22%3A%22%22%7D%7D)
[![Claude Desktop Extension](https://img.shields.io/badge/Claude_Desktop-Add_Extension-D97757)](https://github.com/vectros-ai/vectros-mcp-server/releases/latest/download/vectros.mcpb)

> One-click badges install the **server entry** in your client. You still supply
> a key — run `npx -y @vectros-ai/cli bootstrap` (recommended) or paste your
> `ssk_...`. See [Connect from your client](#connect-from-your-client) and the
> [honest caveats](#honest-caveats).

A [Model Context Protocol](https://modelcontextprotocol.io) server for
**Vectros** — a typed, multi-tenant **record store unified with hybrid
search** and citation-grounded RAG. Deterministic lookups and enumeration
*and* semantic search over one isolated, per-customer index of records and
documents — so an agent gets memory that's precise, not just fuzzy recall.
Reached agent-natively here over MCP (Claude Desktop, Cursor, Claude Code,
Cline, Continue, VS Code, hosted platforms) — and the same data is
human-accessible through the Vectros app + SDKs.

```
npx -y @vectros-ai/mcp-server
```

Your agent can search your indexed corpus, query structured records,
ingest documents, and ask questions grounded against documents — reaching
only your tenant's data, never the public web (there are no web tools).

## Quick start — one command

The fastest way to set up is the [`@vectros-ai/cli`](https://www.npmjs.com/package/@vectros-ai/cli)
`bootstrap` command. It mints a **least-privilege scoped key** (`ssk_*`)
bound to a narrowed AccessProfile, optionally scaffolds a use-case data
model, and safe-merges the `vectros` server into your MCP client config —
no root key, and no hand-editing JSON:

```bash
npx -y @vectros-ai/cli bootstrap
```

You pick what to set up (a blank read-only credential, or a **blueprint**
like task tracking) and sign in once with a token from the
developer portal. The command then:

- mints a scoped `ssk_*` for **this machine** (independently rotatable),
- creates the matching AccessProfile — **data-plane only**; the command
  refuses to provision control-plane scope (keys / profiles / billing / …),
- backs up and merges the entry into `claude_desktop_config.json` (Claude
  Desktop, Cursor, Cline). For **Claude Code**, add `--client code`: it merges
  the project `.mcp.json` and prints the equivalent `claude mcp add` command.

Restart your MCP client and you're done. It's idempotent (re-run any time);
`--rotate` replaces this machine's key.

**Want to browse the data yourself?** `bootstrap` sets up the key for your
*agent*, not a login for *you* — so a blueprint's context won't appear in the
data-plane app's switcher until you join your own user to it (the app lists only
contexts your user has access in). Grant yourself a role once, either in the admin
app (**Access → Contexts → _your context_ → Profiles → Create profile**, pick
yourself from the by-email picker, choose a role — no raw id needed) or from the
CLI with `--principal me` (resolves to your own user):

```bash
vectros access grant --principal me --context <context-id> --role <role>
```

Blueprints that ship a human role (e.g. `agentic-sdlc`'s `editor`) let you use
`--role`; otherwise grant inline scopes with `--actions records:r,search:r,…`.

For scripted / agent use, set the sign-in token in the environment and skip
the prompts:

```bash
VECTROS_BOOTSTRAP_TOKEN=… npx -y @vectros-ai/cli bootstrap \
  --blueprint task-management --yes
```

Prefer to wire it up by hand? See **Configure manually** below.

## Connect from your client

| Client | One-click | Manual |
|---|---|---|
| **Claude Desktop** | [Desktop Extension (`.mcpb`)](https://github.com/vectros-ai/vectros-mcp-server/releases/latest/download/vectros.mcpb) — double-click, paste your key | [JSON snippet](#configure-manually-claude-desktop-or-any-mcp-client) |
| **Cursor** | [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=vectros&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB2ZWN0cm9zLWFpL21jcC1zZXJ2ZXIiXSwiZW52Ijp7IlZFQ1RST1NfQVBJX0tFWSI6IiJ9fQ%3D%3D) | `.cursor/mcp.json`, same shape as below |
| **VS Code** | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=vectros&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40vectros-ai%2Fmcp-server%22%5D%2C%22env%22%3A%7B%22VECTROS_API_KEY%22%3A%22%22%7D%7D) | `.vscode/mcp.json`, same shape |
| **Claude Code** | `claude mcp add` (below) | [project `.mcp.json`](#configure-manually-claude-code) |
| **Cline / Continue** | — | same JSON snippet as Claude Desktop |
| **Smithery** | `npx -y @smithery/cli install @vectros-ai/mcp-server` | — |
| **Codex** | — | TOML snippet (below) |

The fastest path on **every** client is `npx -y @vectros-ai/cli bootstrap` — it
mints a scoped key and writes the config for you. The one-click buttons install
the server entry; you then supply the key (bootstrap, or paste your `ssk_...`).

**Codex** (`~/.codex/config.toml`):

```toml
[mcp_servers.vectros]
command = "npx"
args = ["-y", "@vectros-ai/mcp-server"]
env = { VECTROS_API_KEY = "ssk_live_..." }
```

## Honest caveats

Precision is the pitch — what this server deliberately does *not* do:

- **There's a human step.** Bootstrap needs a developer-portal sign-in / bridge
  token. One command, but a person signs in — there is no fully unattended
  provisioning.
- **No web tools, on purpose.** The agent surface has no web-search or web-fetch
  tools at all. Vectros is the memory, not the browser.
- **Agent document upload is text-inline today.** An agent ingests document text
  inline; on the stdio transport a jailed local-file upload is supported, but
  bulk file upload from the agent surface isn't the path today.
- **Audit history is tamper-*evident*, not tamper-proof.** A state-continuity
  chain makes out-of-band alteration *detectable*; it is not continuous
  automated verification.

## Configure manually (Claude Desktop or any MCP client)

```json
{
  "mcpServers": {
    "vectros": {
      "command": "npx",
      "args": ["-y", "@vectros-ai/mcp-server"],
      "env": {
        "VECTROS_API_KEY": "ssk_live_..."
      }
    }
  }
}
```

Restart Claude Desktop. The agent now sees the Vectros tools and
two resources as callable surfaces.

## Configure manually (Claude Code)

Claude Code reads a project-scoped `.mcp.json` with the same shape — drop this
at your project root (commit it to share the server with the repo):

```json
{
  "mcpServers": {
    "vectros": {
      "command": "npx",
      "args": ["-y", "@vectros-ai/mcp-server"],
      "env": {
        "VECTROS_API_KEY": "ssk_live_..."
      }
    }
  }
}
```

Or let Claude Code's CLI write it for you:

```bash
claude mcp add vectros -e VECTROS_API_KEY=ssk_live_... -- npx -y @vectros-ai/mcp-server
```

Add `-e VECTROS_API_BASE_URL=https://api.staging.vectros.ai` for a non-production
environment. Reopen the project in Claude Code and the Vectros tools are
available.

## Tools (21 tools)

**Search & RAG**

| Tool | What it does |
|---|---|
| `hybrid_search` | Hybrid BM25 + dense search across the tenant's indexed content (records + documents). Narrow by ownership, folder, type, metadata filters, a created date window, and keyword-precision (`textMode`) / relevance floors. Returns the indexed projection of each hit. |
| `rag_ask` | Ask a question grounded against the indexed corpus. Scope retrieval (ownership / folder / type / metadata filters / date window) and steer generation (`instructions` / `temperature`). Streaming generation aggregated; progress notifications keep the call alive for the generation window. |
| `document_ask` | Ask a question grounded against a single document. Same aggregation + progress-notification shape as `rag_ask`. |

**Records** (structured, schema-validated data)

| Tool | What it does |
|---|---|
| `list_schemas` | List the record-schema catalog the credential can see (filter by `surface` or resolve one by `recordType`). Makes `record_query` / `record_create` discoverable. |
| `record_query` | Query records by lookup field (equality / range / prefix, with `asc`/`desc` ordering) or list mode (filter by ownership + type). |
| `record_get` | Fetch one record by id, including its full payload (large payloads truncated to protect the agent context window). |
| `record_create` | Create a record of a given type; idempotent by `externalId`; optional per-record `indexMode`. |
| `record_update` | Patch a record's payload (deep-merged; `null` deletes a key); optimistic concurrency via `expectedVersion`. |
| `record_delete` | Permanently delete a record by id (leaves a tombstone). |

**Documents** (text/file content, indexed for search + Q&A)

| Tool | What it does |
|---|---|
| `document_ingest` | Create a document — inline text body OR local file upload (file mode is stdio-transport only). Idempotent by `externalId`; optional `schemaId` + `payload` for a typed, lookup-queryable document. |
| `document_query` | Query documents by lookup field (equality / range / prefix, with `asc`/`desc` ordering) or list mode (filter by ownersh