MCP server

Explanation — what & why

Vectros ships an official Model Context Protocol (MCP) server (@vectros-ai/mcp-server) that connects MCP-aware agents — Claude Desktop, Cursor, Cline, Continue, VS Code, and hosted agent platforms — directly to a tenant's hybrid search, structured records, documents, folders, and in-perimeter inference. Drop one line into the agent's config and the model can search the indexed corpus, query and write records, ingest documents, and ask questions grounded against documents — with no custom integration code.

The MCP server is a thin shim over the Vectros SDK: partner-observable behavior matches the SDK and the underlying HTTP API one-to-one. Tenant isolation and scope enforcement all hold — running an MCP server does not expand a credential's reach. What it does is make that reach available to the agent as callable tools.

Two properties are worth understanding up front:

Data-plane tools only. The server exposes exactly 19 tools, and every one of them wraps a Vectros data-plane operation. There are no web-search or third-party agent tools — none are present, by design. An agent driven through this server reaches your tenant's data and nothing else.
Built for the context window. A tool result is injected straight into the model's context, a fundamentally different consumption shape than a UI response. The server applies deliberately smaller default limits than the HTTP API to protect the window and the cost.

How-to

Install and configure (stdio — the desktop case)

Drop this into your MCP client config (Claude Desktop: claude_desktop_config.json; Cursor / Cline / Continue have equivalents):

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

Restart the client. That is the whole install. The server runs as a stdio subprocess of the client; JSON-RPC over stdin/stdout is the wire protocol. No ports, no URLs, no auth ceremony.

VECTROS_API_KEY accepts any of the three credential types, but a scoped permanent key (ssk_*) is the right shape for a desktop install — the blast radius of a root key on a desktop is too broad.

Provision the credential in one command

You do not have to hand-build that ssk_*. The companion CLI mints a least-privilege scoped key and its access profile and merges the config entry above for you — no root key, no manual portal steps:

npx -y @vectros-ai/cli bootstrap

See cli.md for the full bootstrap flow. The minted key is data-plane only and per-machine.

Install and configure (HTTP — the hosted case)

For self-hosted scenarios — running the server behind a network boundary, sharing it across agent instances, deploying as a sidecar — the same package exposes a second binary that speaks Streamable HTTP instead of stdio:

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 server listens on 127.0.0.1:8765 by default. A bearer token is optional on localhost but required to bind a non-loopback host — without one, anyone who can reach the port could call Vectros with your credentials, so the server refuses to start (override with VECTROS_MCP_HTTP_ALLOW_INSECURE=1, which is not recommended). DNS-rebinding protection is built in; set VECTROS_MCP_HTTP_ALLOWED_HOSTS to your public hostname(s) when running behind a reverse proxy.

Constrain which tools an agent gets

Narrow the catalog at install time with VECTROS_MCP_TOOLS — a comma-separated list of tool names (e.g. "hybrid_search,rag_ask"). This gives an agent read-only search without exposing writes or inference cost. Unknown tool names fail fast at startup with a clear error.

Reference

The 19 tools

Every tool wraps a Vectros data-plane operation. Records, documents, and folders each have a full create / read / update / delete / query set; search and inference round it out; current_identity and list_schemas are discovery.

Tool	Purpose
`hybrid_search`	Keyword + dense ranking across indexed documents and records.
`list_schemas`	Discover the available record types.
`current_identity`	Describe the credential's tenant and principal scope.
`record_create`	Create a structured record.
`record_get`	Fetch a record by id.
`record_update`	Update a record.
`record_delete`	Delete a record.
`record_query`	Look up (exact / range / prefix) or list records by type.
`document_ingest`	Create a document — inline text, or a local file upload.
`document_get`	Fetch a document by id (metadata + optional text).
`document_update`	Update a document.
`document_delete`	Delete a document.
`document_query`	Look up or list documents.
`document_ask`	Ask a question scoped to a single document.
`folder_create`	Create a folder.
`folder_update`	Update a folder.
`folder_delete`	Delete a folder.
`folder_query`	Look up or list folders.
`rag_ask`	Ask a question grounded against the whole indexed corpus.

There are deliberately no web, search-the-internet, or third-party agent tools — the server's reach is your tenant's data plane only.

Read-only resources

Alongside the tools, the server exposes two read-only MCP resources for ambient context an agent can pick up without spending a tool call:

a schema catalog resource (the same payload as list_schemas), and
an identity resource (the same payload as current_identity).

Transports

Transport	Binary	Default bind	Use for
stdio	`vectros-mcp-server`	n/a (subprocess)	Desktop agents.
Streamable HTTP	`vectros-mcp-server-http`	`127.0.0.1:8765`	Hosted / shared / sidecar deployments.

`document_ingest` is dual-mode

Pass text for an inline-body ingest, or filePath for a local-file upload — exactly one; both is an error.

text mode works on both transports.
filePath mode is stdio-only. The HTTP transport rejects filePath at validation time, because a remote server cannot read the caller's local filesystem. On HTTP, ingest text inline or call the SDK's upload method from your own code.
On stdio, an uploaded path is jailed to a configured ingest root (VECTROS_MCP_INGEST_ROOT, else the server's working directory). Paths that escape the root (traversal, absolute, or symlink) or match a sensitive-file pattern (SSH/AWS/credential files, .env, and similar) are refused before any bytes are read.
File uploads are asynchronous: the tool returns with status PENDING_INDEX; poll document_get until it reports INDEXED.

Context-window protection

Because tool results land directly in the model's context, the server caps results more tightly than the HTTP API:

Tool	API default	API max	MCP default	MCP max
`hybrid_search`	10	50	3	10
`record_query`	100	100	3	10
`rag_ask` retrieval	—	—	5	10

Agents that need more search hits paginate with offset. Agents that want a full document fall back to document_ask for question-driven extraction rather than dumping text into context.

Long-running calls stay alive

rag_ask and document_ask can run tens of seconds. MCP clients have tool-execution timeouts that would otherwise fire mid-generation. The server emits an MCP progress notification for each streamed chunk, keeping the JSON-RPC connection warm; the final aggregated answer arrives as the tool result. Clients that surface progress show the answer building; clients that ignore it still receive the complete answer.

Startup credential validation

On connect, the server performs a credential check so a bad key fails fast as a startup error rather than opaquely failing on the first tool call. Disable it with VECTROS_MCP_SKIP_PING_VALIDATION=1 (useful in CI where the API is not reachable).

Environment variables

Variable	Required	Default	Purpose
`VECTROS_API_KEY`	yes	—	Vectros credential. Recommended: `ssk_*`.
`VECTROS_API_BASE_URL`	no	`https://api.vectros.ai`	API base URL. Use the staging URL for the staging tenant. Validated before the key is attached.
`VECTROS_MCP_TOOLS`	no	(all)	Comma-separated tool filter.
`VECTROS_MCP_INGEST_ROOT`	no	server cwd	Root directory `document_ingest` file uploads are jailed to (stdio).
`VECTROS_MCP_DEBUG`	no	—	Set `1` for debug logging on stderr.
`VECTROS_MCP_SKIP_PING_VALIDATION`	no	—	Set `1` to skip the startup credential check.
`VECTROS_MCP_HTTP_PORT`	HTTP only	`8765`	Listen port.
`VECTROS_MCP_HTTP_HOST`	HTTP only	`127.0.0.1`	Bind address.
`VECTROS_MCP_HTTP_BEARER_TOKEN`	HTTP only	—	Client→server bearer token. Required to bind a non-loopback host.
`VECTROS_MCP_HTTP_ALLOWED_HOSTS`	HTTP only	—	Extra allowed `Host` header values (DNS-rebinding protection).
`VECTROS_MCP_HTTP_ALLOWED_ORIGINS`	HTTP only	—	Extra allowed `Origin` header values.
`VECTROS_MCP_HTTP_ALLOW_INSECURE`	HTTP only	—	Set `1` to bind a non-loopback host without a bearer token (not recommended).

Notes & limits

Exactly 19 data-plane tools; no web/agent tools. The server cannot reach the public internet or any non-Vectros service.
document_ingest file upload is stdio-only. Use text mode (or the SDK) on HTTP.
One upstream credential per process. The HTTP transport uses its VECTROS_API_KEY for all upstream calls; the incoming HTTP bearer token is for client→server auth only, not mapped to a per-request Vectros credential. Deploy one server per credential boundary you want to enforce.
current_identity returns a minimal shape today and gains richer fields (allowed actions, data scope) automatically as the backend rolls them out — no server release needed.
rag_ask / document_ask aggregate before returning. The full answer is assembled server-side (progress notifications cover the latency); native tool-level streaming is not yet exposed.

Where to go next

cli.md — bootstrap provisions the ssk_* this server runs on.
sdk.md — the SDK the tools wrap, for when you want code instead of an agent.
blueprints.md — declare the schemas the agent will read and write.
The blueprint walkthroughs — narrated builds where an agent drives a provisioned blueprint over MCP.