5 Coding Agents
Anton Nesterov edited this page 2026-11-16 04:57:16 +01:00

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:

  1. 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.
  2. The vski CLI on PATH plus a project .env: records, migrations, IaC, pipelines, everything the HTTP API can do, from the shell.
  3. vski mcp as 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/mcp is registered and search_docs answers
  • vski --version works in a fresh shell, installed without sudo
  • .env in the project root carries VSKI_URL and VSKI_API_KEY
  • vski mcp is registered as a stdio server and its tool list arrives