# Clients

Vectros is a REST platform, but you almost never call it with raw HTTP. Four
client surfaces meet you where you are — from a typed SDK in your application
code, to a one-command provisioning CLI, to an agent-native MCP server, to a
declarative blueprint format that stands up a whole app's data model from a
file. Pick the one that fits the job; they all talk to the same API and inherit
the same tenant isolation and scope rules.

| Surface | What it is | Reach for it when… | Doc |
|---|---|---|---|
| **SDK** | Typed client libraries generated from the API spec. Node is the verified reference; Java and Python are also generated. | You are writing application code and want types, pagination helpers, and streaming handled for you. | [sdk.md](sdk.md) |
| **CLI** (`@vectros-ai/cli`, `vectros`) | A command-line tool for provisioning: blueprints, app contexts, identities, scoped keys, access bindings, and a one-shot MCP credential bootstrap. | You want to scaffold or provision from a terminal or CI — without writing code or handling your root key directly. | [cli.md](cli.md) |
| **MCP server** (`@vectros-ai/mcp-server`) | A Model Context Protocol server that exposes the Vectros data plane to AI agents as 21 callable tools. | You want an agent (Claude Desktop, Cursor, and others) to read, write, search, and reason over your tenant's data with no integration code. | [mcp.md](mcp.md) |
| **Blueprints** (`@vectros-ai/blueprints`) | A declarative app-model-as-config format: schemas, an access profile, a service principal, seed data, and roles, all in one file. | You want to describe an app's data model once and provision it idempotently. | [blueprints.md](blueprints.md) |

## How they fit together

The pieces compose into a no-code path from a file to a working, agent-driven
app:

1. A **blueprint** declares the schemas, the least-privilege access profile, a
   service principal, optional seed records, and optional roles.
2. The **CLI** `bootstrap` command reads the blueprint, provisions everything it
   declares, and mints a narrow scoped key (`ssk_*`) — merging it straight into
   your MCP client config.
3. The **MCP server** picks up that key and gives an agent the data-plane tools.
4. Your application code — or a forked reference app — uses the **SDK** for the
   same operations programmatically.

A blueprint can only ever request **data-plane** access (records, schemas,
search, documents, folders, inference). The CLI is the trust boundary: it
hard-refuses any control-plane scope, so even an untrusted, hand-written, or
agent-authored blueprint cannot escalate the credential it provisions.

## A note on versions

The API is specified once and the Node SDK is generated from that spec; the spec
is currently at **0.29.9**. The clients in this repository do not all track the
very latest spec in lockstep — a few capabilities (record/document/folder PATCH,
and the `typeName`-or-`schemaId` choice on record creation) need a 0.26 client.
The **CLI** and **MCP server** already bundle a 0.26 staging build, so they have
them; the **React toolkit** and the **reference web apps** still pin a 0.23
staging build, so those capabilities are not reachable through the reference
apps' UI. Each doc calls out exactly which surface needs the newer SDK; see
[sdk.md](sdk.md) for the full picture.

## Where to go next

- [sdk.md](sdk.md) — install, construct a client, and make your first call.
- [cli.md](cli.md) — the full command catalog and the blueprint lifecycle.
- [mcp.md](mcp.md) — the 21 tools, both transports, and the credential bootstrap.
- [blueprints.md](blueprints.md) — the blueprint format reference.
- The blueprint walkthroughs (getting-started, clinical-intake,
  coding-agent-memory, second-brain) — end-to-end, narrated builds on top of
  these clients.