Docs

Docs

Self-Hosting the MCP Server

Run the Vaadin MCP server inside your own network, on your own host.
Note
Commercial Feature

The self-hosted MCP server is part of the Vaadin Enterprise Edition. It needs a license key entitled to the MCP server, which Vaadin adds to your subscription on request — it cannot be added from your account page yet. The hosted server at mcp.vaadin.com needs no subscription.

Vaadin runs a hosted MCP server at https://mcp.vaadin.com/docs, and for most teams that’s the one to use: there’s nothing to operate, and its documentation is updated every week.

Self-host when your organization can’t send development queries to a service outside its own network. The same server is available as a container image you run on your own host.

This page gets one instance running. The pages under Topics cover each part in detail.

What Self-Hosting Changes

  • The server makes no outbound connections. All the documentation it searches is inside the image, so it needs no route to the internet — only an inbound route from your developers' tools. See Air-Gapped Operation.

  • You can log every tool call. Point the server at a file and it records what each agent asked for. See Audit Logging.

  • Nothing is sent to Vaadin. Usage reporting is off unless you turn it on, and there’s no reason to. See Analytics.

The trade-off: your documentation is only as current as the image you last pulled, where the hosted server updates itself.

To compare against what the hosted server does — where it runs, and what it reports — see What the Hosted Server Runs. It runs the same image you would.

What You Need

  • A container runtime on an x86_64 host. Docker, Podman, or Kubernetes — Deployment Examples has definitions for Compose and Kubernetes. The published image is linux/amd64 only. An arm64 host such as Apple Silicon runs it through emulation, which is slower to start and slower to search — fine for trying out, not for a deployment.

  • A Vaadin Enterprise Edition subscription, with a license key entitled to the MCP server. The server won’t start without one. See Licensing.

  • 1 vCPU and 2 GB of memory per instance. See Sizing and Scaling.

  • Somewhere to run it that your development tools can reach. The server has no authentication, so you control access at the network level — see Network Exposure.

Deployment Modes

Choose one. Both use the same image, the same key, and the same settings, so you can evaluate one way and deploy the other.

A shared internal service is the usual choice: one deployment, such as a Kubernetes pod or a container on an internal VM, that every developer’s tools connect to. You install and renew one key, collect audit records in one place, and update one image. Deployment Examples has a complete definition for this.

A container per developer runs the same image on each developer’s own machine. Use it to evaluate the server, or where a shared internal service isn’t allowed. The downside is repetition: you install the key on every machine and update every machine’s image separately.

Running the Server

1. Pull the Image

Images are published to vaadin/mcp-server on Docker Hub:

Source code
bash
docker pull vaadin/mcp-server:latest

Use a permanent tag in anything you deploy, rather than :latest. Both :latest and a plain version number change over time: the version number tracks the server code, so a documentation update republishes the same version under a new timestamp. Only the full tag names a single build.

Finding a Tag

Browse the image’s tags on Docker Hub, or list the newest from a terminal:

Source code
bash
curl -s 'https://hub.docker.com/v2/repositories/vaadin/mcp-server/tags?page_size=25' \
    | jq -r '.results[] | select(.name != "latest") | .name' | sort -r | head

The tags read <version>-<YYYYMMDD-HHMMSS>-<commit>, newest first, so the top entry is the current build:

Source code
vaadin/mcp-server:1.0.0-20260916-114956-2b7c708

To confirm which build you ended up with, read the running server’s vaadin-mcp://image-info resource over MCP. It reports the same commit the tag names.

2. Install the License Key

You need a server license key entitled to the MCP server — Licensing explains how to request one. With the key file in hand, the quickest way to start the server is to pass the key’s contents in an environment variable:

Source code
bash
docker run --rm -p 8080:8080 \
    -e VAADIN_OFFLINE_KEY="$(cat /path/to/serverKey)" \
    vaadin/mcp-server:latest

This works anywhere, but the key is then visible to anyone who can run docker inspect. For a real deployment, or to use Docker, Compose, or Kubernetes secrets, mount the key file instead. See Option B: Mounted Key File.

3. Check That It Started

The server prints one line as it starts:

Source code
ready. License valid until 2027-04-30.

You can also ask the running container. Its health endpoint is /health, not /actuator/health:

Source code
bash
curl -s http://localhost:8080/health | jq '.components.license.details.license'
Source code
JSON
{ "status": "valid", "expiresAt": "2027-04-30T00:00:00Z" }

If the server didn’t start, If the Server Doesn’t Start lists each message and what to do about it.

Open http://localhost:8080/ in a browser for a page of ready-made configuration snippets, carrying your own endpoint URL rather than Vaadin’s.

Pointing Your Tools at It

The MCP endpoint is /docs. For a deployment on mcp.example.com, configure your tools with:

Source code
https://mcp.example.com/docs

Follow the MCP Setup Guide for your tool, and use your own URL wherever it shows https://mcp.vaadin.com/docs. Nothing else in those instructions changes.

To serve the endpoint on a different path, or to run the server behind a proxy that rewrites URLs, see Behind a Reverse Proxy.

Network Exposure

The server has no authentication. Both the MCP endpoint and the health endpoint answer anyone who can reach them.

Control access at the network level instead:

  • Put the server behind your existing ingress or reverse proxy, and apply your own authentication there.

  • Restrict it to the networks your developers and build agents run on.

  • Don’t publish it to the internet.

Keeping the Documentation Current

The documentation is part of the image, so to update it you pull a newer image and restart. Vaadin rebuilds the current release against the latest documentation every week and republishes it under the same version with a new timestamp, so expect a fresh image roughly weekly even when the server code hasn’t changed.

The server stores no data, so upgrading means stopping the old container and starting the new one. Read the release notes when the version number changes — that signals a change your tools can see, such as a tool, parameter, or response field.

To check what a running instance is serving, read its vaadin-mcp://image-info resource over MCP. It reports the build date, the exact build it came from, which documentation version each part was built from, and the license status. Quote it in a support request: it identifies the build precisely, where a tag can be ambiguous.

Topics

Licensing
Request, install, verify, and renew the license key the server needs to start.
Deployment Examples
Complete Docker Compose and Kubernetes definitions for a shared internal server.
Configuration
Every environment variable the self-hosted MCP server reads, and how to place it behind a reverse proxy.
Air-Gapped Operation
How to get the image into a disconnected network, and what the server sends.
Monitoring and Audit Logging
What to monitor, what to alert on, and how to record every tool call.
Sizing and Scaling
What one instance needs, and how to add capacity.

Resources

Updated –