Documentation

Deploy MCP servers#

Use the kmcp controller to automatically spin up your MCP server in a Kubernetes environment.

Prerequisites#

Deploy the MCP server#

Learn how you can deploy an MCP server in a Kubernetes cluster. Choose between the following options:

Option 1: Deploy an MCP server with npx or uvx#

Deploy an instance of the server-everything MCP server by using the npx or uvx command. This server provides simple tools, such as an echo tool, that you can use for testing. Choose between using the kmcp CLI or creating the MCPServer resource yourself.

  1. Deploy the MCP server.

    kmcp deploy package --deployment-name my-mcp-server \
    --manager npx --args @modelcontextprotocol/server-everything

  2. Verify that the MCP server is up and running.

    kubectl get pods

    Example output:

    NAME                             READY   STATUS    RESTARTS   AGE
    my-mcp-server-669bcb5d6f-zv5dn   1/1     Running   0          27h

  1. Create the MCPServer resource.

    kubectl apply -f- <<EOF  
    apiVersion: kagent.dev/v1alpha1
    kind: MCPServer
    metadata:
      name: my-mcp-server
      namespace: default
    spec:
      deployment:
        args:
        - '@modelcontextprotocol/server-everything'
        cmd: npx
        port: 3000
      stdioTransport: {}
      transportType: stdio
    EOF

  2. Verify that the MCP server is up and running.

    kubectl get pods

    Example output:

    NAME                             READY   STATUS    RESTARTS   AGE
    my-mcp-server-669bcb5d6f-zv5dn   1/1     Running   0          27h

Option 2: Build and deploy an MCP server#

Learn how to use the kmcp CLI to build an image for your MCP server and to deploy the server to your Kubernetes cluster. The following example assumes that you created a FastMCP or MCP Go project with a sample MCP server and tool, and that your kind cluster is named kind.

  1. Build a Docker image for your MCP server and load it to your kind cluster.

    kmcp build --project-dir my-mcp-server -t my-mcp-server:latest --kind-load-cluster kind

  2. Deploy your MCP server. Choose between the kmcp CLI or manually creating an MCPServer resource.

    The kmcp deploy command automatically creates an MCPServer resource in your cluster that contains the MCP server configuration that is defined in the kmcp.yaml file in your MCP project. The kmcp controller then uses this resource to spin up and manage the lifecycle of your MCP server. After the MCP server is deployed, the command automatically starts the MCP inspector tool so that you can test your server.

    Tip: If you do not want to start the MCP inspector tool, add the --no-inspector flag to the command.

    kmcp deploy --file my-mcp-server/kmcp.yaml --image my-mcp-server:latest

    You can manually create an MCPServer resource yourself as shown in the following examples.

    • FastMCP example
    kubectl apply -f- <<EOF
    apiVersion: kagent.dev/v1alpha1
    kind: MCPServer
    metadata:
      name: my-mcp-server
    spec:
      deployment:
        image: "my-mcp-server:latest"
        port: 3000
        cmd: "python"
        args: ["src/main.py"]
      transportType: "stdio"
    EOF
    • MCP Go example:
    kubectl apply -f- <<EOF
    apiVersion: kagent.dev/v1alpha1
    kind: MCPServer
    metadata:
      name: my-mcp-server
    spec:
      deployment:
        image: "my-mcp-server:latest"
        port: 3000
        cmd: "./server"
      transportType: "stdio"
    EOF

  3. Verify that the MCP server is up and running.

    kubectl get pods

    Example output:

    NAME                             READY   STATUS    RESTARTS   AGE
    my-mcp-server-669bcb5d6f-zv5dn   1/1     Running   0          27h

Test access to the MCP server#

  1. Run the MCP inspector tool. Note that if you used the kmcp deploy command to spin up your MCP server, the MCP inspector tool is already running. You can skip to the next step.

    1. Port-forward the MCP server that you deployed.

      kubectl port-forward deploy/my-mcp-server 3000

    2. Run the MCP inspector tool. In your CLI output, find the URL that the MCP inspector tool is exposed on.

      npx @modelcontextprotocol/inspector

      Example output:

      🚀 MCP Inspector is up and running at:
      http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=8aca1a7088efc984e433fd750ed042b1881fbda3734282e3f0e524b00fc3e69f

  2. In your MCP inspector tool, click Connect to connect to your MCP server. Note that it might take a few seconds for the MCP inspector tool to successfully connect to your MCP server. If the connection fails, make sure the following fields are set in the MCP inspector tool.

    • Select Streamable HTTP from the Transport Type drop down.
    • Enter http://127.0.0.1:3000/mcp in the URL field.
    • Expand the Configuration section and make sure that the Proxy Session Token is set to the value of the PROXY_AUTH_TOKEN that was shown in the CLI output when you opened the MCP inspector tool.
    Connect to FastMCP server with MCP inspector tool
    Connect to FastMCP server with MCP inspector tool

  3. Try out the built-in echo MCP tool.

    1. Go to the Tools tab and click List Tools.
    2. Select the echo tool.
    3. Enter any string in the message field, such as Hello world and click Run Tool.
    4. Verify that you see your message echoed in the Tool result card.
    Successful run of the echo tool
    Successful run of the echo tool

Next#

Learn how to manage secrets for your MCP servers.

Kagent Lab: Discover kagent and kmcp
Free, on‑demand lab: build custom AI agents with kagent and integrate tools via kmcp on Kubernetes.
Start the Lab