Vectros Mcp Server

@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%22VECTROSAPIKEY%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 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  --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

| Client | One-click | Manual | |---|---|---| | Claude Desktop | Desktop Extension (.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%22VECTROSAPI_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):

[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

| 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 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, and (where surfaced) allowedActions + dataScope. | | lookup_principal | Resolve a user / org / client by your own externalId (→ its Vectros UUID, for the ownership filters) or by a schema lookup field. Read-only. | | version_history | Read the audit/version trail (CREATE/UPDATE/DELETE, with actor + diff) for one record or document. Read-only. |

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

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

| Var | Required | Default | Purpose | |---|---|---|---| | VECTROS_API_KEY | yes | — | Vectros API key. Accepts sk_* / ssk_* / st_*; ssk_* recommended. | | 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:

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 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 on

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vectros-ai
• Source: vectros-ai/vectros-mcp-server
• License: Apache-2.0
• Homepage: https://docs.vectros.ai

Install and usage instructions live in the source repository linked above.