Self-Hosting

The Vultr Model Context Protocol (MCP) Server is a server that gives MCP clients read-only access to Vultr infrastructure. The server is in public preview. Vultr hosts a copy at https://mcp.vultr.com/mcp, and you can run your own copy when you need the server inside your own environment.

This guide explains how to run your own copy of the Vultr MCP Server locally over standard input and output (STDIO), locally over HTTP, in a Docker container, and on Kubernetes, and how to connect a client to your server. A self-hosted server is read-only like the hosted server, and no setting turns on tools that change state.

Prerequisites

Before you begin, you need to:

• Have a workstation or server with Git, Python 3.12 or later, and uv installed.
• Have a Vultr API key to run the server over STDIO and to test tool calls over HTTP.
• Install Docker to run the server in a container.
• Have kubectl access to a Kubernetes cluster and Helm installed to run the server on Kubernetes.

Get the Source

The server runs from the project repository. Clone the repository so that every later step has a working directory.

1. Clone the repository.

   CONSOLE

   Copy

   $ git clone https://github.com/vultr/vultr-mcp.git

   Explain Code

   Powered by Vultr AgentBeta

2. Change to the repository directory.

   CONSOLE

   Copy

   $ cd vultr-mcp

   Explain Code

   Powered by Vultr AgentBeta

3. List the directory contents.

   CONSOLE

   Copy

   $ ls

   Explain Code

   Powered by Vultr AgentBeta

   Your output should be similar to the one below:

   Dockerfile
   README.md
   docs
   interface
   k8s
   openapi.json
   pyproject.toml
   scripts
   src
   tests
   uv.lock

Run Over STDIO

With STDIO, an MCP client launches the server as a child process and exchanges messages with it through standard input and output. A web request does not carry a login in this mode, so the server uses a Vultr API key that you provide as an environment variable.

1. Install the dependencies.

   CONSOLE

   Copy

   $ uv sync

   Explain Code

   Powered by Vultr AgentBeta

2. Set your Vultr API key. Replace VULTR_API_KEY with your key.

   CONSOLE

   Copy

   $ export VULTR_API_KEY=VULTR_API_KEY

   Explain Code

   Powered by Vultr AgentBeta

3. Send an initialize request to the server to verify that it starts.

   CONSOLE

   Copy

   $ printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}' | uv run python -m vultr_mcp

   Explain Code

   Powered by Vultr AgentBeta

   The command writes one MCP request to the standard input of the server. The server prints a startup banner, answers the request, and exits when the input closes. Your output includes a response similar to the one below:

   {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18", ... "serverInfo":{"name":"Vultr MCP Server","version":"2.1.24"}}}

To use the server with a client, configure the client to launch uv run python -m vultr_mcp from the repository directory with VULTR_API_KEY set in the environment of the client.

Run Over HTTP

Over HTTP, the server listens for Streamable HTTP requests and provides a health check. Each request carries its own credential, exactly like the hosted server, so the server does not use an API key from its own environment.

1. Start the server.

   CONSOLE

   Copy

   $ VULTR_MCP_TRANSPORT=http uv run python -m vultr_mcp

   Explain Code

   Powered by Vultr AgentBeta

   The server listens on port 8080, and the command does not return.

2. In a second terminal, send a request to the health check.

   CONSOLE

   Copy

   $ curl http://localhost:8080/healthz

   Explain Code

   Powered by Vultr AgentBeta

   Your output should be similar to the one below:

   {"status":"ok","service":"vultr-mcp-server","version":"2.1.24","read_only":true}

3. Call a tool with your Vultr API key as the bearer credential. Replace VULTR_API_KEY with your key.

   CONSOLE

   Copy

   $ curl -X POST http://localhost:8080/mcp \
       -H "Content-Type: application/json" \
       -H "Accept: application/json, text/event-stream" \
       -H "Authorization: Bearer VULTR_API_KEY" \
       -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"vultr_account_get","arguments":{}}}'

   Explain Code

   Powered by Vultr AgentBeta

   The response contains the details of your Vultr account.

4. Send the same request without the Authorization header.

   The response contains the error Vultr API returned 401: Invalid API token. The server does not fall back to the API key in its environment.

The server also serves each product area on its own path, such as /mcp/compute, which serves only the compute tools. For the list of paths, see Tools.

Run in Docker

The repository includes a Dockerfile that builds the server as a container image. The image starts the server over HTTP as a non-root user, so a container exposes the same health check and tool paths as a local HTTP server.

1. Build the image from the repository directory.

   CONSOLE

   Copy

   $ docker build -t vultr-mcp:latest .

   Explain Code

   Powered by Vultr AgentBeta

2. Start a container.

   CONSOLE

   Copy

   $ docker run -d --rm --name vultr-mcp -p 8080:8080 -e VULTR_MCP_TRANSPORT=http vultr-mcp:latest

   Explain Code

   Powered by Vultr AgentBeta

   The command prints the container ID.

3. Send a request to the health check.

   CONSOLE

   Copy

   $ curl http://localhost:8080/healthz

   Explain Code

   Powered by Vultr AgentBeta

   Verify that the output contains "status":"ok".

4. Stop the container. Docker removes the container because the --rm option is set.

   CONSOLE

   Copy

   $ docker stop vultr-mcp

   Explain Code

   Powered by Vultr AgentBeta

Run on Kubernetes

The repository includes the Kubernetes manifests that the hosted server runs from. They deploy the server with a shared Redis instance for login state and publish it through a Traefik ingress. The manifests contain the domain and the OAuth application settings of the hosted server, so adapt them to your own environment before you apply them.

1. Install Traefik with the values file from the repository.

   CONSOLE

   Copy

   $ helm install traefik traefik/traefik --namespace traefik --create-namespace -f k8s/traefik/values.yaml

   Explain Code

   Powered by Vultr AgentBeta

2. Copy the secret example.

   CONSOLE

   Copy

   $ cp k8s/secret.yaml.example k8s/secret.yaml

   Explain Code

   Powered by Vultr AgentBeta

3. Open the k8s/secret.yaml file in a text editor.

   CONSOLE

   Copy

   $ nano k8s/secret.yaml

   Explain Code

   Powered by Vultr AgentBeta

4. Add the following values to the stringData section, and then save and close the file:

   • VULTR_OAUTH_CLIENT_SECRET: The secret of your approved Vultr OAuth application.
   • VULTR_API_KEY: An optional fallback credential. Leave the value empty when OAuth is enabled.

5. Open the k8s/configmap.yaml file in a text editor.

   CONSOLE

   Copy

   $ nano k8s/configmap.yaml

   Explain Code

   Powered by Vultr AgentBeta

6. Replace the MCP_RESOURCE_URL, VULTR_OIDC_PROVIDER_ID, and VULTR_OAUTH_CLIENT_ID values with the values for your own domain and OAuth application, and then save and close the file. To run without OAuth, set VULTR_OIDC_ENABLED to "false". Clients then send a Vultr API key as the bearer credential.

7. Open the k8s/ingress.yaml file in a text editor.

   CONSOLE

   Copy

   $ nano k8s/ingress.yaml

   Explain Code

   Powered by Vultr AgentBeta

8. Replace both occurrences of mcp.vultr.com with your own domain name, and then save and close the file.

9. Apply the manifests.

   CONSOLE

   Copy

   $ kubectl apply -f k8s/

   Explain Code

   Powered by Vultr AgentBeta

10. Wait for the deployment to finish rolling out.

    CONSOLE

    Copy

    $ kubectl rollout status deployment/vultr-mcp

    Explain Code

    Powered by Vultr AgentBeta

    Verify that the output shows deployment "vultr-mcp" successfully rolled out.

The deployment runs two replicas behind the ingress. The server uses stateless HTTP, so the ingress does not need session affinity.

Connect a Client

A client reaches your own server in one of two ways. Over STDIO, the client launches the server itself and passes it your Vultr API key. Over HTTP, the client connects to a server that is already running and sends your Vultr API key with every request. Choose the way that matches how you run the server.

Connect over STDIO

The client starts and stops the server, so you do not need a running server. Each client needs the path to the repository that you cloned and your Vultr API key.

1. Add the server to Claude Code. Replace REPOSITORY-PATH with the full path to the cloned repository, and replace VULTR_API_KEY with your key.

   CONSOLE

   Copy

   $ claude mcp add vultr-selfhosted -e VULTR_API_KEY=VULTR_API_KEY -- uv run --directory REPOSITORY-PATH python -m vultr_mcp

   Explain Code

   Powered by Vultr AgentBeta

2. List the configured servers.

   CONSOLE

   Copy

   $ claude mcp list

   Explain Code

   Powered by Vultr AgentBeta

   Verify that the vultr-selfhosted entry shows Connected.

For Cursor, add the following entry to mcp.json. For VS Code, add the same entry to the servers object in .vscode/mcp.json with "type": "stdio". Replace REPOSITORY-PATH and VULTR_API_KEY as before.

{
  "mcpServers": {
    "vultr-selfhosted": {
      "command": "uv",
      "args": ["run", "--directory", "REPOSITORY-PATH", "python", "-m", "vultr_mcp"],
      "env": {
        "VULTR_API_KEY": "VULTR_API_KEY"
      }
    }
  }
}

Connect over HTTP

The client connects to a server that you started in the previous sections, so keep that server running. The client sends your Vultr API key as the bearer credential with every request.

1. Add the server to Claude Code. Replace VULTR_API_KEY with your key.

   CONSOLE

   Copy

   $ claude mcp add --transport http vultr-selfhosted-http http://localhost:8080/mcp --header "Authorization: Bearer VULTR_API_KEY"

   Explain Code

   Powered by Vultr AgentBeta

2. List the configured servers.

   CONSOLE

   Copy

   $ claude mcp list

   Explain Code

   Powered by Vultr AgentBeta

   Verify that the vultr-selfhosted-http entry shows Connected.

For Cursor, add the following entry to mcp.json. For VS Code, add the same entry to the servers object in .vscode/mcp.json with "type": "http". Replace VULTR_API_KEY as before.

{
  "mcpServers": {
    "vultr-selfhosted": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer VULTR_API_KEY"
      }
    }
  }
}

If you run the server on Kubernetes with OAuth enabled, clients log in the same way as with the hosted server. Use the address of your own domain followed by /mcp in place of https://mcp.vultr.com/mcp. For more information, see Client Setup.

To verify any connection, ask the client What Vultr account am I connected as? The response shows the account that your Vultr API key belongs to.

Configuration

The server reads its settings from environment variables. Set the following variables to change the behavior of the server:

• VULTR_MCP_TRANSPORT: Sets the transport to stdio (default) or http.
• VULTR_API_KEY: Provides the credential for STDIO. The server ignores it over HTTP.
• VULTR_API_BASE_URL: Sets the Vultr API address. The default is https://api.vultr.com/v2.
• SERVER_HOST and SERVER_PORT: Set the HTTP bind address. The default is 0.0.0.0:8080.
• SSL_VERIFY: Controls whether the server verifies upstream TLS. The default is true.
• VULTR_MCP_EXCLUDED_CATEGORIES: Lists the categories to leave out. The default is the identity set. An empty value keeps everything.
• VULTR_MCP_CATEGORY_ENDPOINTS: Lists the endpoints to serve by name, such as compute,network. The default is all nine endpoints.
• VULTR_MCP_INTERFACE: Set to off to serve only the tools generated from the API specification. The default is on.
• VULTR_MCP_INTERFACE_DIR: Sets the directory of reviewed tool definitions. The default is interface/.
• VULTR_MCP_INTERFACE_MAX_PAGES: Sets the number of pages that one filtered search can scan. The default is 10.
• VULTR_MCP_OUTPUT_SCHEMAS: Controls whether the server advertises generated output schemas. The default is false.
• MCP_RESOURCE_URL: Sets the public URL of the server, which the server uses for OAuth and the allowed host list. The default is https://mcp.vultr.com.
• MCP_ALLOWED_HOSTS: Adds extra hosts to accept.
• MCP_ALLOWED_ORIGINS: Adds extra Origin values for the OAuth consent page.
• VULTR_OIDC_ENABLED: Turns on OAuth. The default is false.
• VULTR_OIDC_PROVIDER_ID, VULTR_OAUTH_CLIENT_ID, and VULTR_OAUTH_CLIENT_SECRET: Provide the credentials of the approved OAuth application.
• REDIS_HOST and REDIS_PORT: Set the shared OAuth state. Required when you run more than one replica.
• VULTR_MCP_AUDIT_DIR: Also writes audit records to files in this directory, for a log shipper.

Audit Records

The server records each tool call so that you can see which identity ran which tool and whether it succeeded. Audit records capture the identity, tool, request ID, and outcome, and never include argument values or result contents.

The server writes each audit record as a JSON line. Over HTTP, the records go to standard output. Over STDIO, they go to standard error, because standard output carries the protocol messages. Set VULTR_MCP_AUDIT_DIR to also write the records to files in that directory, one file per event type, for a log shipper to read.

Conclusion

You have run your own copy of the Vultr MCP Server and connected a client to it. For the list of tools that your server provides, see Tools. For more information, visit the Vultr MCP Server repository.