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 get401. A truly public function needs a token-authenticated pipeline step of typeplugininstead (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; preferplugin://targets where available.
- 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