2 MCP Server Tutorial
Anton Nesterov edited this page 2026-11-03 22:29:56 +01:00

Tutorial: MCP Server

How to build an MCP (Model Context Protocol) service on top of vski: one image that runs a headless vski deployment (the data, and the plugin that maintains it) beside an MCP server that agents talk to. The worked example is the vski docs MCP, live at https://mcp.vski.ai/mcp and built from the docs_mcp repository; this page generalizes it so the same shape fits any MCP service (internal tools, company knowledge bases, operations surfaces).

flowchart LR
    A["coding agent"] -->|"vski mcp (stdio or http)"| V["VSKI deployment<br/>(REST API as tools)"]
    A2["any coding agent"] -->|"docs MCP (public http)"| D["vski docs MCP"]
    D -->|"records + vectors + graph"| KB["VSKI deployment<br/>(docs knowledge base)"]

Two different things, both useful to agents: vski mcp wraps an existing deployment's REST API as tools (deployment management), while a purpose-built MCP server like the one in this tutorial serves one domain (read-only, curated, public). The rest of this page is about building the second kind.

The shape

flowchart LR
    subgraph image ["one image, one container"]
        subgraph vski ["headless vski server"]
            P["plugin<br/>(warm, python)"]
            C["collections + vectors<br/>+ graph"]
        end
        M["MCP server<br/>(Streamable HTTP)"]
    end
    CI["CI workflows"] -.->|"ships + converges"| image
    CR["cron"] -->|"pipeline://"| PL["pipeline"]
    PL -->|"plugin step"| P
    S["external sources"] --> P
    A["coding agents"] -->|"MCP tools"| M
    M -->|"reads"| C

One container, three concerns:

  • The vski server holds the data (records, vectors, graph) and runs the plugin that maintains it. Headless, on container port 3000; dashboards connect to it directly.
  • The MCP server is a small python process (fastmcp, Streamable HTTP) on the platform port. It only reads, through an API key from its environment.
  • CI converges everything: the workflows deploy the image and apply the IaC; the cron keeps the data fresh. Nothing is created or applied inside the container.

1. Design the tools first

Decide what agents get before writing code. The docs MCP's answers are a good template:

  • Read-only surface. The MCP tools never write; every mutation happens in the plugin, on a schedule or a pipeline kick. A public service then needs no secrets from its callers at all.
  • Links, not copies. Docs results are canonical URLs (the docs site page and the raw markdown), never re-served content; agents fetch the canonical source themselves. Serve full content only for things that are yours to serve (the docs MCP serves example-repo code and comments in full, because those repos are the canonical examples).
  • Related references in one round trip. A graph with the canonical relationships (page links, semantic similarity edges, page-to-repo references) lets every search result carry its related pages and repos without additional calls.

2. The MCP server module

A thin layer over the SDK client: build the client from the environment, then register tools that read through it. Sketch from the docs MCP (docsmcp/server.py):

def build_server(client):
    from fastmcp import FastMCP

    mcp = FastMCP("my-service", instructions=...)

    @mcp.tool
    async def search(query: str, limit: int = 5) -> str:
        """What the tool returns, for the agent to decide when to call it."""
        vector = await query_vector(query)   # see step 3
        resp = await client.embeddings.search("sections", vector, limit=limit * 3)
        return json.dumps(rank(resp), indent=2)

    return mcp

The process waits for /health, requires its key from the environment, and binds MCP_PORT / PORT. If tools need embeddings, get the vectors by invoking a plugin function (next step) so the provider key never reaches the MCP process.

3. Background work lives in a plugin

Anything slow (cloning, crawling, embedding) belongs in a plugin, invoked by a pipeline on a cron schedule. Two patterns that matter:

  • Ack fast, finish in the background, then signal. A plugin step's invoke timeout caps at 120 seconds, but the work can take minutes: acknowledge immediately (return {"queued": True}, run the job with asyncio.create_task), wrap blocking IO in asyncio.to_thread, and write the outcome to a collection agents can inspect. The step also passes {{run.id}}; when the background job lands, the plugin completes the run it came from:

    await ctx.client.workflow.send_signal(run_id, "index-done", result)
    

    A signal step in the pipeline (type: signal, name: index-done) parks the run until that arrives, and a final report step re-raises an error payload so a failed pass fails the run. The run's state and output then tell the truth; watch it with vski runs list / vski runs show or the dashboard. (Signal delivery needs a server where plugin keys carry the workflows role; on older servers the run stays waiting after the ack.)

  • Secrets arrive as pipeline params. The plugin's provider keys are stored as pipeline secrets (secrets.yaml with fromEnv, values read from CI or .env at iac apply time), resolved by the executor as {{secrets.NAME}} into step params. The plugin function receives the resolved value and caches it for query-time use; the key never sits in YAML, container environment, or the MCP process.

All writes go through the plugin's role-scoped key: collections carry rules like 'plugin' in @request.auth.roles for create/update/delete and public read.

4. Declare the deployment in IaC

Everything the deployment is lives in vski/ YAML (see IaC): the database and collections with their rules, the graph, the plugin instance (config: clone URLs, endpoint, model), the pipeline with its secrets-resolved params, the cron schedule, and the secrets declarations. vski plan diffs it against the deployment; vski apply converges it. Local development is the same loop through a Makefile (make up / make iac-apply / make reindex / make search).

5. One image

A Dockerfile FROM vski.sh/x/vski:latest plus your package, the plugin manifest, and a tiny run.sh supervisor: vski in the background, the MCP server on the platform port, restart the MCP process if it exits, end the container only if vski dies. EXPOSE the MCP port and 3000; state lives under /app/data (mount the persistent volume there).

6. Ship it with CI/CD

Two stages in one workflow: a deploy job ships the image (host resources, TLS ports, runtime env), and the bootstrap job after it converges the state with the vski CLI (vski admins ensure, vski iac apply, one pipeline kick). The full pattern, secrets taxonomy and runbook: CI/CD.

The worked example

The docs MCP indexes the platform wiki (discovering the canonical example repos from the docs themselves, comments included) into records, vectors and a knowledge graph, and serves five tools:

Tool What it returns
search_docs(query) Ranked pages: docs.vski.ai URL + raw-markdown URL + matching section anchor, with related pages/repos from the graph
list_docs() Every indexed page and example repo, as links
search_code(query, language?, kind?) Example files and code comments by meaning, with source URLs
get_example(repo, path) Full source of one example file
index_status() Latest indexer runs: counts, repos, skips, errors

Embeddings go through one OpenAI-compatible client (Gemini's endpoint by default; any provider works, local Ollama for development), and the model must match between indexing and queries. The full source, tests and workflow files: https://vski.sh/x/docs_mcp.