Vectros MCP Server

@vectros-ai/mcp-server

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.

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)

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

{
  "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:

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

Records (structured, schema-validated data)

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

Folders (group records + documents)

Identity & history

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

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 orgId. 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.

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 env VECTROS_API_KEY). 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 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-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 for the per-plan limits.

Building from source

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) — the published npm package is self-contained and works without .npmrc config on the consumer's machine.

License

Apache-2.0. See the LICENSE file.