3 MCP
Anton Nesterov edited this page 2026-11-08 20:25:29 +01:00

vski mcp

vski mcp exposes a VSKI deployment as MCP (Model Context Protocol) tools, so coding agents can manage and operate the deployment from their editing loop: create collections, run records CRUD, trigger pipelines, invoke plugin functions, watch workflow runs, and everything else the HTTP API allows. It is a command of the Python SDK CLI and is aimed at deployment management and operations; for building your own MCP service on top of vski, see Tutorial: MCP Server.

Setup

pip install "vski-sdk[mcp]" --extra-index-url https://vski.sh/api/packages/x/pypi/simple/
export VSKI_URL=https://vski.example
export VSKI_API_KEY=...          # admin role unlocks plugins and pipelines
vski mcp                         # stdio: speaks MCP on stdin/stdout
vski mcp --http 9090             # Streamable HTTP on http://127.0.0.1:9090/mcp

Credentials come from the normal CLI resolution (flags, VSKI_URL / VSKI_API_KEY / VSKI_TOKEN / VSKI_DB env, .env, vski login): the MCP server forwards them on every API call and sends the default database as the x-dbname header, exactly like the SDK.

| Option | Default | Description | | --- | --- | | --http PORT | off | Serve Streamable HTTP instead of stdio | | --host | 127.0.0.1 | Bind address in --http mode | | --timeout | 60 | Per-request API timeout (seconds) |

Register it with an MCP client that supports stdio servers:

{
  "mcpServers": {
    "vski": {
      "command": "vski",
      "args": ["mcp"],
      "env": { "VSKI_URL": "https://vski.example", "VSKI_API_KEY": "..." }
    }
  }
}

Or point an HTTP-capable client at http://127.0.0.1:9090/mcp. There is no extra auth layer: the server is exactly as privileged as the credentials it was started with, so bind it to localhost or put it behind an authenticating reverse proxy when it must be reachable remotely.

The tool surface

The server builds itself from the deployment's own OpenAPI spec (GET /openapi.json, kept current by the server): every REST operation becomes one MCP tool named after its operationId, so the surface always matches the deployed version. Expect tools like listDatabases, createCollection, listRecords, searchRecords, createGraphEdges, runSql, createCronJob, triggerWebhook. The plugin and workflow-run endpoints are covered by a small supplemental spec, giving tools like invokePluginFunction, listPluginInstances, listWorkflowRuns, getWorkflowRun and cancelWorkflowRun. Calls that need a database use the one from VSKI_DB (or --db) via the x-dbname header.

Check that it works

With the HTTP transport, one call proves the whole chain (auth, spec fetch, API round trip):

from fastmcp import Client

async with Client("http://127.0.0.1:9090/mcp") as client:
    tools = await client.list_tools()
    result = await client.call_tool("listCollections", {})

For stdio, point the client at the vski mcp command and list tools; if the tool list arrives, auth and connectivity are fine.

Calling plugin functions from external services

Plugin invocation over HTTP (POST /api/plugin-instances/{name}/invoke) requires authentication. External services that hold only a low-privilege key can still call a specific plugin function through a gate with a plugin:// target (see Gates for the full picture):

# once, as admin: expose tagger.on_photo through a gate
curl -X POST "$VSKI_URL/api/collections/_gates/records" \
  -H "X-API-Key: $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "tagger-invoke",
    "url": "plugin://tagger/on_photo",
    "rules": "*"
  }'

# any authenticated caller the rule allows can now invoke the function;
# the body is the function's params, and the result comes back verbatim:
curl -X POST "$VSKI_URL/api/gates/tagger-invoke" \
  -H "X-API-Key: $VIEWER_KEY" -H "Content-Type: application/json" \
  -d '{"id": "1", "image": "a.jpg"}'

Three things to know:

  • rules: "*" means "any authenticated principal". The gate route sits behind the global auth middleware, so anonymous callers get 401. A truly public function needs a token-authenticated pipeline step of type plugin instead (POST /api/pipelines/trigger/{token}); that path is fire-and-forget, it returns a run id rather than the function result.
  • With a plugin://<instance>/<function> target the function identity is fixed by the gate record; callers only pick the payload. The call rides the plugin invoke budget (30 s default, 120 s cap).
  • On servers without plugin targets, the same is achievable by pointing the gate at the instance's invoke route with an injected admin key (url: http://127.0.0.1:3000/api/plugin-instances/tagger/invoke?db=gallery, headers: "{\"X-API-Key\": \"<admin key>\"}"; a JSON-encoded string). Caveat: there the caller's body selects the function, so anyone passing the rule can invoke any function on that instance; prefer plugin:// targets where available.