Vectros Ai

@vectros-ai/mcp-server

[npm] [license]

[Add to Cursor] [Install in VS Code] [Claude Desktop Extension]

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 and the honest caveats.

A Model Context Protocol 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 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:

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):

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:

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

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):

[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)

If @vectros-ai/cli is installed globally (npm install -g @vectros-ai/cli, not a one-off npx run — the server needs vectros to still be on PATH later, when IT runs, not just while bootstrap ran) and you've run vectros bootstrap with it, omit the env block entirely — the server resolves your key from the local vectros CLI keyring automatically (see Credential resolution below). vectros login alone does not do this — it stores a separate sign-in session, not this key — so bootstrap is the step that actually has to have run:

{  "mcpServers": {    "vectros": {      "command": "npx",      "args": ["-y", "@vectros-ai/mcp-server"]    }  }}

No CLI installed, or a machine you can't log in on? Set the key directly instead:

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

This file lives under Claude Desktop's own per-user app-support directory, not a shared repo — but a real key pasted into it is still a live secret at rest: don't paste it into a chat, ticket, or screenshot with the value intact, and prefer the keyring form above whenever you can.

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. Never commit a real key into it — .mcp.json is exactly the kind of file teams check in to share a project's tooling, and a live ssk_*/sk_* value inside it is a credential leak the moment it lands in git history, not just if the repo is public.

The way to share this config safely: commit the entry with no env block at all, and let each developer's own vectros CLI keyring supply the key (see Credential resolution below — this is the same delegation git credential / docker-credential-* use). This needs each teammate to have @vectros-ai/cli installed globally and to have run vectros bootstrap with it — npx-ing the CLI once, or running vectros login alone (a separate sign-in session, not this key), leaves nothing on PATH or in the keyring for the server to find later:

{  "mcpServers": {    "vectros": {      "command": "npx",      "args": ["-y", "@vectros-ai/mcp-server"]    }  }}

Or let Claude Code's CLI write that keyring-based entry for you:

claude mcp add vectros -- npx -y @vectros-ai/mcp-server

If a machine genuinely has no vectros CLI installed, you can pass the key directly with -e VECTROS_API_KEY=ssk_live_... — but then keep that config local: add .mcp.json to .gitignore first, rather than committing it with the key inside.

Add -e VECTROS_API_BASE_URL=<your environment's API base URL> to point the server at a different 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 another registry, a bare npx -y @vectros-ai/mcp-server can resolve a build other than the public release. 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 (23 tools)

Search & RAG

Records (structured, schema-validated data)

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

Folders (group records + documents)

Identity & history

All 23 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.

Concurrent updates. record_update, document_update, folder_update and document_ingest with upsert: true return 409 (errorCode: VERSION_CONFLICT) when another request changed the same item at the same moment, whether or not you pass expectedVersion. Nothing is written and the other change is kept: re-read the item and retry. expectedVersion still refuses an update made against a version you read earlier, even if the other change finished long ago. An update to an item that was deleted a moment earlier returns 404. In record_batch_write with upsert, an item that meets another change at the same moment is reported in the results with status: conflict and errorCode: VERSION_CONFLICT; send that item again. Items written with atomicity: all_or_nothing are not covered.

Items of a deleted schema. An item whose schema no longer exists is not served: reading it (record_get, document_get) returns an error, updating it, reading its version_history, and reading a document's text, download or answers (document_ask) are refused, and record_query, document_query and record_batch_get leave it out. Delete the item.

Routing a call through your own model provider

rag_ask and document_ask take an optional providerAlias: the alias of a model provider config your Vectros account has activated. When you pass it, that one call is served by your own provider instead of the platform-hosted default, and model then names a model on your provider's own id space (it falls back to that provider config's default model when omitted). The server forwards providerAlias only when you supply it and never fills it in.

It works only after your account has set up the provider and signed the platform's risk-acceptance waiver. Without both, the platform refuses the call with a 403, which the tool returns to you as written. When the waiver is the cause, the 403 carries an errorCode that says which case it is: WAIVER_NOT_SIGNED (the waiver has not been signed), WAIVER_TEXT_CHANGED (it was signed, but its text changed afterwards, so the earlier signature no longer counts) or WAIVER_REVOKED (an account owner revoked it). An account owner resolves each in the developer portal (Model Providers); retrying the call does not help.

If your account has accepted the Business Associate Agreement with Vectros in the developer portal, an account owner must also attest each provider config in the developer portal (Model Providers) before a call can use it. Until then the platform refuses the call with a 403 that says it needs a BAA-holder attestation. The owner does this in the portal; nothing in this server does it.

A call served by your own provider leaves the platform-hosted Bedrock path, and Vectros's AWS BAA boundary, so decide deliberately whether a given call should use it. Nothing here is a statement about how a provider you chose handles your data.

Opting into a subset

Pass VECTROS_MCP_TOOLS=hybrid_search,record_query,record_get to register only those three — useful for giving an agent read-only access without exposing ingestion or inference costs to the credential. Add rag_ask or document_ask only if the credential should be able to spend inference balance. Unknown tool names fail fast at startup.

Resources

Two read-only resources for ambient context (no tool call required):

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 a read-only AccessProfile (any name, for example mcp-read), and drop the resulting ssk_live_... into the config above.

See the Vectros developer documentation on scoped tokens for least-privilege credential setup — the vectros bootstrap flow provisions a scoped ssk_* key and its AccessProfile in one command.

A root sk_* can no longer file into another app context, as of API 0.43.0. If you run this server on a root key and a tool call names a folderId / parentFolderId — or a schemaId on a document — belonging to a context other than default, it is now refused with a uniform 400 "Folder not found" / "Schema not found". This affects document_ingest, document_update, record_create, record_update and folder_create, and it is a change in outcome: those calls used to succeed. They never did what they appeared to, though — a root key's writes are always stamped default, so the row landed in default while its folder or schema lived elsewhere, permanently invisible to the context that owned them. Existing rows written the old way are untouched and still readable, updatable and deletable. The fix is the same scoped key recommended above: one bound to the target context can file into it and always could.

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 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 (CLI 0.10.0+) 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 (CLI 0.10.0+) shows which entry is active and which of your keys are live.

Environment variables

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:

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:

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 deliberately doesn't expose

This is a decision, not a backlog. An MCP server is a tool surface handed to an autonomous caller, so a capability the API offers is not automatically a tool — each one has to earn its place on an agent's surface.

The line is the data plane: records, documents, folders and search are here in full. Anything that grants or administers authority is not, and neither is the design-time layer that defines the data model.

• Stored scripts (/v1/scripts — push, list, fetch, delete). A stored script is code, not data. Authoring it is a design-time act, the same reason schema mutation lives in the CLI rather than here: an agent that can write the code that later runs under your credential is a different proposition from one that can write records.
• Synchronous script execution (POST /v1/scripts/execute, the scripts:x scope). The closer call of the two, and excluded on operational grounds rather than reach — a scripts:x:<name> grant is a deliberately narrow, per-script permission, and an ordinary scoped key can hold it. What an agent handles badly is the failure surface: a run whose outcome cannot be determined returns 500 EXECUTION_OUTCOME_UNKNOWN with writes that may or may not have committed, which is not something a caller resolves by retrying — it has to go and look. Getting a retry right also means reusing an Idempotency-Key across attempts, and a tool call has no natural retry identity, so an agent re-invoking after a timeout would silently run the script a second time. Exposing this well needs a deliberate design for those two things, not a thin wrapper. Until then, run scripts from a caller that can handle them — the API, the SDK, or the CLI.
• Trigger rules (/v1/triggers). Declaring a rule grants authority — a rule's scopes/roleIds are live, and declaring one is scope-monotonicity-checked like any other authority-granting surface. Minting authority is not an agent action.
• Trigger failure history (GET /v1/trigger-failures) and usage/billing (GET /v1/usage). Both are read-only, and both are operational rather than data-plane — they describe how your automation and your account are behaving, not what your content says. That is a question for the developer portal or the CLI, where a person is looking at it, rather than a tool an agent reaches for mid-task.
• Identity, access and credential administration — users, access profiles, roles, app contexts, issuer registrations, and scoped-key minting. Unchanged since launch: identity CRUD stays off the agent tool surface by design. lookup_principal resolves an identifier to an id and does nothing else.
• Compliance operations (erasure, export). Same reason.

If one of these belongs on your agent's surface, that's worth telling us — the line is drawn on purpose and can be redrawn with a reason.

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 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-minute rate limits as any API client; the rate limits guide says which requests count. On a rate-limit 429 the tool returns the error with HTTP 429 and errorCode: RATE_LIMITED, so the agent can pace and retry rather than blind-retrying. rag_ask and document_ask can also return 429 with errorCode: BALANCE_BUSY (your pre-paid balance is momentarily busy with your other concurrent requests: not a rate limit and not a shortage, so do not top up; retry shortly) or 503 with errorCode: BALANCE_UNAVAILABLE (a temporary fault interrupted the balance step; also not a shortage; retry shortly). A 402 means the balance is short (INSUFFICIENT_BALANCE) or the plan's usage limit is reached (SUBSCRIPTION_LIMIT_EXCEEDED). A 503 with no errorCode on a call that names a providerAlias means the platform cannot open the stored provider key: retry shortly, and enter the key again in the developer portal if it persists. The tool returns the message, errorCode and requestId, not the Retry-After header. The guide also lists the per-plan limits.

Building from source

git clone https://github.com/vectros-ai/vectros-mcp-servercd vectros-mcp-servernpm installnpm run buildnpm 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) — 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.

Tool output is untrusted, API-supplied content. Every tool here returns your own tenant's data — document text, search results, error messages — as plain text inside the MCP response. This server does not sanitize, escape, or pre-render that text, and none of these tools evaluate or execute it. Render tool output the same way you'd render any other data an agent pulled from an external source — safely, in your client — rather than eval-ing it or trusting it as pre-sanitized.

License

Apache-2.0. See the LICENSE file.