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
Section titled “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
Section titled “Claude Code”claude plugin marketplace add https://vski.sh/x/harness_pluginclaude plugin install vski@vskiOr 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.
/plugin marketplace add https://vski.sh/x/harness_pluginthen 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 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_plugincd harness_plugin./scripts/install-codex.shIt 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
Section titled “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
Section titled “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
Section titled “2. The CLI on PATH”pip install "vski-sdk[cli]" --extra-index-url https://vski.sh/api/packages/x/pypi/simple/vski --versionIf 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 linespyenv install 3.12 # compiles from source; needs the usual build packagespyenv global 3.12 # or `pyenv local 3.12` to keep it per-projectpip 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
Section titled “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:3000VSKI_API_KEY=vski_... # mint with: vski keys create dev --roles adminVSKI_DB=gallery # optional: the default databaseAny 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)
Section titled “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
Section titled “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
Section titled “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