io.github.vectros-ai/mcp-server
Typed record store + hybrid search over MCP: deterministic lookups + semantic memory, per-customer.
Open source Open in the app JSON README (API)
About
Typed record store + hybrid search over MCP: deterministic lookups + semantic memory, per-customer.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- vectros-ai
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.16.1
- Stars
- 3
- Last push
- 2026-08-30T23:30:44Z
- Repository state
- ativo
- Language
- TypeScript
- License
- Apache-2.0
- Added
- 2026-08-29 04:01:38
- Updated
- 2026-08-31 00:00:07
- Origin id
io.github.vectros-ai/mcp-server
README
# @vectros-ai/mcp-server
[](https://www.npmjs.com/package/@vectros-ai/mcp-server)
[](https://www.apache.org/licenses/LICENSE-2.0)
[](https://cursor.com/install-mcp?name=vectros&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB2ZWN0cm9zLWFpL21jcC1zZXJ2ZXIiXSwiZW52Ijp7IlZFQ1RST1NfQVBJX0tFWSI6IiJ9fQ%3D%3D)
[](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)
[](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** | [](https://cursor.com/install-mcp?name=vectros&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB2ZWN0cm9zLWFpL21jcC1zZXJ2ZXIiXSwiZW52Ijp7IlZFQ1RST1NfQVBJX0tFWSI6IiJ9fQ%3D%3D) | `.cursor/mcp.json`, same shape as below |
| **VS Code** | [](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.
**Load it into a session by restarting.** A Claude Code session that was
already open when you added the server won't pick it up mid-session — fully
quit and reopen the project (not just re-select the tab). The `/mcp` panel
shows the connector marketplace, not locally-configured stdio servers, so it
won't confirm the server is loaded — ask the agent to call a Vectros tool
instead. Config is keyed by the **git common root**, so a linked worktree
resolves to its main repo's `.mcp.json` — add and open from the same project.
> **Windows note:** if your `.npmrc` (or a global npm config) points the
> `@vectros-ai` scope at a private registry, a bare `npx -y @vectros-ai/mcp-server`
> can resolve an unexpected internal build there instead of the public
> release — and an internal build is not guaranteed to run on Windows. If the
> command above fails to start, either remove the scoped-registry override
> for a plain `npx` run, or pin an explicit version (`npx -y
> @vectros-ai/mcp-server@<version>`) known to work.
## Tools (22 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 (`value`), range, or prefix, with `asc`/`desc` ordering and an optional `sortFrom`/`sortTo` window — or list mode (filter by ownership + type). Also supports composite equality across 2-3 fields (`values`), but only against a lookup the *schema* declares over those fields together (see `list_schemas`) — not any two fields you pick. |
| `record_get` | Fetch one record by id, including its full payload (large payloads truncated to protect the agent context window). |
| `record_batch_get` | Fetch several records by id (1-100) in one call, each with its full payload. Returns `missingIds` for any requested id you can't access, since the API silently omits them. |
| `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 ownership + type). |
| `document_get` | Fetch a document by id (metadata incl. lifecycle `status` + processing `indexStatus`; optional text truncated at ~8K tokens; optional presigned `downloadUrl` for file-backed documents). |
| `document_update` | Patch a document's metadata / typed payload (deep-merged); archive/restore via `status` (`ARCHIVED` soft-retracts from search, `ACTIVE` restores); optimistic concurrency via `expectedVersion`. |
| `document_delete` | Permanently delete a document by id (removes it and its indexed content). |
**Folders** (group records + documents)
| Tool | What it does |
|---|---|
| `folder_query` | Get a folder by id, or list folders (a parent's children for tree navigation, or a flat tenant list; paginated via `nextCursor`). |
| `folder_create` | Create a folder. |
| `folder_update` | Update a folder's name / description / ownership (merge-patch; optimistic concurrency via `expectedVersion`; folders cannot be re-parented). |
| `folder_delete` | Delete a folder. |
**Identity & history**
| Tool | What it does |
|---|---|
| `current_identity` | Describe the credential: tenantId, environment, principalType, principalKeyId, principalLabel, and (for scoped credentials) allowedActions + dataScope. Does **not** yet include `granted_capabilities` (`member-lifecycle` / `forensic-read` / `context-directory-read` / `delegate-mint`, as of API 0.40.0, joined by `delegate-principal-stamp` in 0.42.0) — a separate reach dimension a scope clause can carry that `/v1/ping` doesn't report yet, so allowedActions + dataScope may understate a credential's true reach. Also reports this server's own version and the bundled SDK version (`mcpServerVersion`, `sdkVersion`). |
| `lookup_principal` | Resolve a user, or an identity entity in a namespace (`org`/`client`/any namespace you registered), by your own `externalId` (→ its Vectros UUID, for the ownership filters) or by a schema lookup field. Pass `contextId` to target a specific app context for a context-owned namespace. Read-only. |
| `version_history` | Read the audit/version trail (CREATE/UPDATE/DELETE, with actor + diff) for one record or document. Read-only. |
All 22 tools wrap published Vectros HTTP API endpoints. JSON
responses are what the agent sees as tool output. Per-call cost
surfaces via the `usage` field on inference responses.
### Opting into a subset
Pass `VECTROS_MCP_TOOLS=hybrid_search,rag_ask` to register only those
two — useful for giving an agent read-only search access without
exposing ingestion or inference costs to the credential. Unknown tool
names fail fast at startup.
## Resources
Two read-only resources for ambient context (no tool call required):
| URI | What it returns |
|---|---|
| `vectros://schemas` | Same payload as `list_schemas`. Lets the agent preload schemas into context for ambient discovery. |
| `vectros://identity` | Same payload as `current_identity`. Lets the agent self-describe without spending a tool call. |
## Recommended credential
Use a **scoped permanent API key** (`ssk_*`), not a root key (`sk_*`).
A scoped key is bound to a narrowed `AccessProfile` — e.g. read-only
across one org scope (`scope:org`). If your MCP install is compromised, the blast
radius is whatever the profile allows, not the whole tenant. The
server emits a `warn` log line on startup when you pass a wildcard
`sk_*` for exactly this reason.
**The easiest way to get one is `npx -y @vectros-ai/cli bootstrap` (above)**
— it mints a least-privilege `ssk_*` and an AccessProfile for you, no root
key required. To do it by hand instead: mint a scoped key from the developer
portal under **Keys → Create scoped key**, bind it to an AccessProfile
titled `mcp-read-all` or `mcp-read-scoped`, and drop the resulting
`ssk_live_...` into the config above.
See the Vectros developer documentation on scoped tokens ("Recommended
AccessProfile for MCP") for least-privilege credential setup — the
`vectros bootstrap` flow provisions a scoped `ssk_*` key and its AccessProfile
in one command.
## Credential resolution
The server resolves its API key from the first source that yields one:
1. **`VECTROS_API_KEY`** — always wins when set.
2. **The `vectros` CLI keyring** — if the key is unset and
[`@vectros-ai/cli`](https://www.npmjs.com/package/@vectros-ai/cli) **0.9.0+** is on
your `PATH`, the server runs `vectros keyring show --format raw` as a subprocess
and uses the key it prints. By default that is your **active** identity; set
`VECTROS_KEYRING_ALIAS` to pick a specific entry. This is the same pattern as
`git credential` / `docker-credential-*` / `aws credential_process`: the key
lives in one place, and the server, your scripts, and your agent hooks all read
it from there instead of each keeping a plaintext copy that drifts.
3. **Neither** — startup fails with a message naming both options.
The resolved key is held in memory and never logged. Startup logs which alias it
resolved (not the key), so you can tell at a glance which identity the server is
running as — `vectros keyring doctor` shows the same view.
> **Startup warns when it picks an identity you didn't name.** If `VECTROS_API_KEY`
> is unset and no `VECTROS_KEYRING_ALIAS` is set, the server falls back to your
> **active** keyring entry and logs a warning — it is running as whatever identity
> `vectros switch` last selected, which may be a `ssk_live_*` key acting on real data
> or a `ssk_test_*` one that isn't. Either can be an unwelcome surprise, because a
> blank placeholder (`"VECTROS_API_KEY": ""` in a client config, or `-e VECTROS_API_KEY`
> passing through an unset var in Docker) reads as "not configured yet" but resolves
> like an unset key. Nothing is blocked — name an entry with `VECTROS_KEYRING_ALIAS`,
> or set `VECTROS_API_KEY`, and the warning goes away. `vectros keyring doctor` shows
> which entry is active and which of your keys are live.
## Environment variables
| Var | Required | Default | Purpose |
|---|---|---|---|
| `VECTROS_API_KEY` | no\* | — | Vectros API key. Accepts `sk_*` / `ssk_*` / `st_*`; `ssk_*` recommended. \*Required **unless** the `vectros` CLI is installed with a usable keyring entry — see [Credential resolution](#credential-resolution). Takes precedence when set. |
| `VECTROS_KEYRING_ALIAS` | no | (the active entry) | Resolve this `vectros` keyring entry instead of the active one. Ignored when `VECTROS_API_KEY` is set. |
| `VECTROS_API_BASE_URL` | no | `https://api.vectros.ai` | Override for staging or other envs. Validated: must be `https://` (or `http://` to localhost) and an official `*.vectros.ai` host. |
| `VECTROS_ALLOW_INSECURE_BASE_URL` | no | — | Set `1` to bypass the base-URL allow-list (e.g. a trusted local proxy). **Not recommended** — sends your key to an unvalidated host; logs a warning. |
| `VECTROS_MCP_INGEST_ROOT` | no | process cwd | Directory `document_ingest`'s `filePath` mode is jailed to. Paths escaping it (traversal/absolute/symlink) or matching a sensitive pattern are rejected. |
| `VECTROS_MCP_TOOLS` | no | (all tools) | Comma-separated tool names (e.g. `hybrid_search,rag_ask`). |
| `VECTROS_MCP_DEBUG` | no | — | Set `1` for verbose stderr logs. |
| `VECTROS_MCP_SKIP_PING_VALIDATION` | no | — | Set `1` to disable the startup `/v1/ping` check. |
| `VECTROS_MCP_HTTP_PORT` | HTTP only | `8765` | Port for HTTP transport. |
| `VECTROS_MCP_HTTP_HOST` | HTTP only | `127.0.0.1` | Bind address. Use `0.0.0.0` for all interfaces (then set a bearer token). |
| `VECTROS_MCP_HTTP_BEARER_TOKEN` | HTTP only | — | Client→server bearer token. **Strongly recommended** beyond localhost; **required** for a non-loopback bind. |
| `VECTROS_MCP_HTTP_ALLOWED_HOSTS` | HTTP only | — | Comma-separated extra `Host` values to allow (DNS-rebinding protection). Set to the public hostname(s) behind a reverse proxy. |
| `VECTROS_MCP_HTTP_ALLOWED_ORIGINS` | HTTP only | — | Comma-separated extra `Origin` values to allow. |
| `VECTROS_MCP_HTTP_ALLOW_INSECURE` | HTTP only | — | Set `1` to permit a non-loopback bind without a bearer token. **Not recommended.** |
## Startup credential validation
Before the first tool call, the server runs a `GET /v1/ping` check
against your credential. Bad keys fail at startup with a clear
error instead of opaquely 401'ing mid-conversation. Set
`VECTROS_MCP_SKIP_PING_VALIDATION=1` to disable.
## HTTP transport
For hosted-MCP scenarios — running the server behind a network
boundary, sharing it across multiple agent instances, deploying as
a sidecar — the package also ships an HTTP binary:
```bash
VECTROS_API_KEY=ssk_live_... \
VECTROS_MCP_HTTP_PORT=8765 \
VECTROS_MCP_HTTP_BEARER_TOKEN=$(openssl rand -hex 32) \
npx -y -p @vectros-ai/mcp-server vectros-mcp-server-http
```
> The HTTP binary is **not** the default — select it explicitly with
> `npx -p <pkg> vectros-mcp-server-http`. A bare `npx -y @vectros-ai/mcp-server`
> always starts the stdio server.
The server listens on `http://127.0.0.1:8765/mcp` by default. The
bearer token is optional but **strongly recommended for any
deployment beyond localhost** — without it, anyone who can reach the
port can call Vectros with your credentials.
Health probe lives at `GET /healthz` (always unauthenticated, k8s
readiness-friendly).
Current limitation: the server uses one upstream credential per process
(the key resolved at startup). Per-request credential override via the
incoming Authorization header is a planned enhancement. For now, deploy one
server per credential boundary you want.
## Programmatic use (advanced)
Most consumers use the CLI shape above. If you need to embed the
server in your own Node process:
```ts
import { VectrosMCPServer, createStdioTransport } from '@vectros-ai/mcp-server';
const server = new VectrosMCPServer({
apiKey: process.env.VECTROS_API_KEY!,
tools: ['hybrid_search', 'rag_ask'],
resources: ['schemas'], // opt-in resource filter; default = all
validateOnStart: true, // default — set false to skip startup ping
});
await server.connect(createStdioTransport());
```
## What this server doesn't do (yet)
- **No prompts capability** — `/rag` and `/ingest_pdf` slash-command
templates land in a future release. (Provisioning — the `bootstrap` command — lives
in the separate [`@vectros-ai/cli`](https://www.npmjs.com/package/@vectros-ai/cli)
package, above.)
- **HTTP transport is single-tenant per process** — per-request
credential override via incoming Authorization header is a v1.0+
enhancement.
- **No Python implementation** — TS only. Python users can `npx`
this server from any project.
- **`rag_ask` and `document_ask` are not natively streaming** —
full answer aggregated before the tool returns. Progress
notifications cover the latency. Native MCP-spec streaming lands
when the spec stabilizes.
The server is on a pre-1.0 track toward a stable 1.0 release.
## Rate limits
Tool calls hit the same per-account per-minute rate limit as any API client (writes, searches,
and inference count against it; reads do not). On a `429` the server surfaces the error with its
`Retry-After` hint so the agent can pace and retry rather than blind-retrying. See the
[rate limits guide](https://docs.vectros.ai/guides/operations-trust/rate-limits) for the per-plan
limits.
## Building from source
```sh
git clone https://github.com/vectros-ai/vectros-mcp-server
cd mcp-server
npm install
npm run build
npm test
```
`npm install` pulls `@vectros-ai/sdk` from the configured npm
registry.
`npm run build` runs `tsup` to produce the dual ESM/CJS output in
`dist/`. The SDK is bundled into the build (see
[`tsup.config.ts`](./tsup.config.ts)) — the published npm package is
self-contained and works without `.npmrc` config on the consumer's
machine.
## Security & trust
Vectros enforces per-customer, fail-closed isolation and least-privilege scoped keys, with a
tamper-evident audit and version history. Customer-facing surfaces are hardened through extensive
adversarial security review. For the full trust posture, drawn plainly with its boundaries, see the
[compliance and trust guide](https://docs.vectros.ai/guides/operations-trust/compliance).
## License
Apache-2.0. See the LICENSE file.