Coding Agents
VSKI is built to be driven by coding agents: the documentation is searchable
over MCP, the whole API is scriptable from the vski CLI, and a deployment
can be managed from the editing loop as MCP tools.
The fastest start is the vski plugin:
one install registers the docs MCP server, the VSKI skills, and the /vski:
commands. It is packaged for Claude Code, ZCode, and Codex. Everything
else (any other harness, the vski CLI, and the deployment MCP server) is
covered by the manual configuration below.
Installing the plugin
The plugin ships the vski-docs MCP server, the docs, examples,
app-dev, and dashboard skills, and the /vski:docs, /vski:example, and
/vski:status commands. The dashboard skill covers dashboard
widgets: opening /w/... surfaces and the /connect
handoff for a browser that is not signed in yet.
Claude Code
claude plugin marketplace add https://vski.sh/x/harness_plugin
claude plugin install vski@vski
Or from inside a session: /plugin marketplace add vski https://vski.sh/x/harness_plugin, then install vski from the /plugin browser. Verify with /mcp: the vski-docs server should be connected.
ZCode
/plugin marketplace add https://vski.sh/x/harness_plugin
then install vski from the plugin browser. Skills appear as vski:docs,
vski:examples, vski:app-dev, vski:dashboard; MCP tools as
mcp__vski_vski-docs__*.
Codex
Codex has no plugin system, but supports remote MCP servers and the same
SKILL.md skill format. The installer script wires both up:
git clone https://vski.sh/x/harness_plugin
cd harness_plugin
./scripts/install-codex.sh
It registers [mcp_servers.vski-docs] in ~/.codex/config.toml (via
codex mcp add when available, TOML append otherwise) and copies the skills
to ~/.agents/skills/vski-*. --uninstall removes exactly what it added.
Restart Codex afterwards.
Manual configuration
The plugin above already registers the docs MCP for Claude Code, ZCode, and Codex. The rest of the environment, and every other harness (OpenCode, anything MCP-capable), is configured by hand the same way everywhere. The minimal environment is three pieces:
- The docs MCP at
https://mcp.vski.ai/mcp: search and read this documentation and the example repositories from the editing loop. Already registered if you installed the plugin above. - The
vskiCLI on PATH plus a project.env: records, migrations, IaC, pipelines, everything the HTTP API can do, from the shell. vski mcpas a stdio server: the deployment itself as MCP tools, picking its credentials from the same.env.
A project created with vski init already
ships the .env plumbing for pieces 2 and 3 (.env.example, Makefile,
venv target); this section explains each piece on its own so it works with
any setup.
1. The docs MCP
https://mcp.vski.ai/mcp is a hosted, public MCP endpoint (Streamable
HTTP, no auth) that indexes docs.vski.ai and the example repositories
(the app template, the agent and frontend templates, the tutorial
projects), so the agent reads canonical, current answers instead of
guessing from training data:
| Tool | What it returns |
|---|---|
search_docs |
Semantic search over the docs; ranked matches as canonical URLs with section anchors |
list_docs |
Every documentation page with its category |
search_code |
Full-text search over the example repositories, code and comments |
get_example |
One file from an example repository |
index_status |
What the indexer currently covers |
The index refreshes automatically as the docs change. Being a remote server, the entire registration is the URL:
{
"mcpServers": {
"vski-docs": { "url": "https://mcp.vski.ai/mcp" }
}
}
2. The CLI on PATH
pip install "vski-sdk[cli]" --extra-index-url https://vski.sh/api/packages/x/pypi/simple/
vski --version
If pip refuses to write (externally-managed-environment on newer system
Pythons, or a plain permission error), do not use sudo and do not paste
--break-system-packages; install an owned Python with pyenv instead:
curl -fsSL https://pyenv.run | bash # then follow its printed shell-setup lines
pyenv install 3.12 # compiles from source; needs the usual build packages
pyenv global 3.12 # or `pyenv local 3.12` to keep it per-project
pip install "vski-sdk[cli]" --extra-index-url https://vski.sh/api/packages/x/pypi/simple/
A project virtualenv works just as well when one already exists; the
requirement is only a writable environment that puts vski on PATH.
vski doctor verifies the whole setup afterwards (server reachable,
credentials resolving, versions).
The project .env
The CLI and vski mcp resolve the target deployment identically: flags,
then the VSKI_URL / VSKI_API_KEY / VSKI_TOKEN / VSKI_DB
environment variables, then a .env in the working directory, then the
vski login config (see Command Line). For a project that
means one git-ignored file in the repo root:
# .env (git-ignored; the template ships .env.example)
VSKI_URL=http://127.0.0.1:3000
VSKI_API_KEY=vski_... # mint with: vski keys create dev --roles admin
VSKI_DB=gallery # optional: the default database
Any vski command run from the project root picks it up, and so does the
stdio server below. Real environment variables win over the file, so a CI
export overrides it cleanly, and the secret never has to live in an MCP
config.
3. vski mcp (stdio)
vski mcp exposes a deployment as MCP tools: one per REST operation plus
plugin and workflow-run helpers, built live from the deployment's own
OpenAPI spec. See the vski mcp reference for the tool surface
and options. It speaks stdio, so registration is a local command:
{
"mcpServers": {
"vski": { "command": "vski", "args": ["mcp"] }
}
}
Started from the project root, it reads the project .env above; the
config snippet stays identical on every machine and carries no secrets.
If the harness launches stdio servers somewhere else, point at the file
explicitly (--env-file is a root option, so it goes before the
subcommand):
{ "command": "vski", "args": ["--env-file", "/abs/path/to/.env", "mcp"] }
One thing to keep in mind: the server is exactly as privileged as the
credentials it starts with. Scope the key (vski keys create takes roles)
and set VSKI_DB rather than handing an admin key to everything.
Registering servers in the harness
Every MCP-capable harness understands the same two shapes used above: a remote server named by URL, and a local stdio command. They differ only in where the config lives, and each documents that itself:
| Harness | Where MCP servers are configured |
|---|---|
| Claude Code | .mcp.json at the repo root, or claude mcp add |
| Codex | [mcp_servers] tables in ~/.codex/config.toml |
| OpenCode | the mcp key in opencode.json |
| ZCode | Settings, MCP Servers, or ~/.zcode/cli/config.json |
Checklist
A checkout is agent-ready when all of this holds:
https://mcp.vski.ai/mcpis registered andsearch_docsanswersvski --versionworks in a fresh shell, installed without sudo.envin the project root carriesVSKI_URLandVSKI_API_KEYvski mcpis registered as a stdio server and its tool list arrives
- Introduction
- Performance
- Getting Started
- Coding Agents
- Command Line
- Infra as Code
- CI/CD Guide
- Project Boilerplate
- SDKs
- Authentication
- Databases
- Collections
- Gated Queries
- Graphs
- Rules and Access Control
- Granular Access Control
- Triggers
- Plugins
- Containers Plugin
- vski mcp
- Realtime
- Full Text Search
- Vector Embeddings
- KWH
- Workflows
- Pipelines
- Dashboard Widgets
- Connectors
- Cron
- Webhooks
- Gates
- Migrations
- Replication
- File Sync
- Backup
- Distributed Realtime
- Tutorial: ReactJS Todo
- Tutorial: Graph-Memory Agent
- Tutorial: Image Gallery
- Tutorial: Embeddings
- Tutorial: Graphs
- Recipe: Calendar Timetree
- Tutorial: Plugins
- Tutorial: MCP Server