mcp-server-http-streamable

A minimal Model Context Protocol (MCP) server using Streamable HTTP transport. It exposes a greeting tool and runs as an HTTP service so clients can connect over the network. The project uses uv both locally and in Docker/Kubernetes for a single, consistent approach. You can run it locally with uv run mcp-server, from Git with uvx, or in Docker/Kubernetes.

Project structure

mcp-server-http-streamable/
├── src/mcpserver/
│   ├── __init__.py
│   ├── __main__.py      # Entry point (mcp-server)
│   └── server.py        # FastMCP app and tools
├── k8s/                 # Kubernetes manifests (00-, 01-, 02-)
├── pyproject.toml       # Project and [project.scripts] mcp-server
├── uv.lock
├── Dockerfile
├── docker-compose.yml
└── README.md

Prerequisites

• Python 3.12+
• uv (recommended) or pip

For Docker: Docker and Docker Compose.

For Kubernetes deploy: kubectl and a cluster (minikube, kind, EKS, etc.).

Deploy to Kubernetes

Follow these steps to build the image, push it to a registry, and run the server in Kubernetes.

Manifests (in k8s/): 00-namespace.yaml, 01-deployment.yaml, 02-service.yaml — numbered so kubectl apply -f k8s/ runs them in the right order.

1. Build the Docker image (from the project root; image uses uv like local):

   docker build -t douglasqsantos/mcp-server-http-streamable:latest .
   

2. Push the image to Docker Hub (or your registry):

   docker push douglasqsantos/mcp-server-http-streamable:latest
   

   Log in first with docker login if needed.

3. Deploy to the cluster (namespace, deployment, and service):

   kubectl apply -f k8s/
   

   Manifests are numbered (00-namespace.yaml, 01-deployment.yaml, 02-service.yaml) so they apply in the correct order.

4. Wait for the pod to be ready:

   kubectl -n mcp-server get pods -l app=mcp-server-http-streamable
   

   Wait until STATUS is Running and READY is 1/1.

5. Access the MCP server:

   • Port-forward (works on any cluster):

     kubectl -n mcp-server port-forward svc/mcp-server-http-streamable 8000:8000
     

     Use http://localhost:8000/mcp in your MCP client. Leave the command running.

   • NodePort (if you use the NodePort service): use http://<NODE_IP>:30800/mcp. Get node IP with kubectl get nodes -o wide or minikube ip (minikube).

6. Update and redeploy after image changes:

   docker build -t douglasqsantos/mcp-server-http-streamable:latest .
   docker push douglasqsantos/mcp-server-http-streamable:latest
   kubectl -n mcp-server rollout restart deployment/mcp-server-http-streamable
   

7. Remove the deployment:

   kubectl delete -f k8s/
   

How to run

Option 1: Local (uv)

From the project directory:

uv sync
uv run mcp-server

The server listens on http://0.0.0.0:8000 by default. The MCP endpoint is at http://localhost:8000/mcp.

Environment variables (optional):

Variable	Default	Description
MCP_HOST	0.0.0.0	Bind address
MCP_PORT	8000	Port

Example with a custom port:

MCP_PORT=9000 uv run mcp-server

Option 2: Run with uvx (from Git)

Install and run from the repository without cloning (requires uv):

uvx --from git+https://github.com/douglasqsantos/mcp-server-http-streamable.git mcp-server

Use your repo URL if different. The server runs with the same defaults (port 8000, endpoint http://localhost:8000/mcp). To use a different port, set MCP_PORT before running (e.g. in your shell or in the process that invokes uvx).

Option 3: Docker

The image uses uv (same as local) so dependency install and run match your usual workflow. Build and run:

docker build -t mcp-server-http-streamable .
docker run -p 8000:8000 mcp-server-http-streamable

The server is available at http://localhost:8000/mcp.

Option 4: Docker Compose

Build and start the service (foreground):

docker compose up --build

Run in the background:

docker compose up --build -d

Stop:

docker compose down

Port 8000 is mapped to the host. Connect to http://localhost:8000/mcp from your MCP client.

Option 5: Kubernetes

Manifests in k8s/ (00-namespace.yaml, 01-deployment.yaml, 02-service.yaml) deploy the image douglasqsantos/mcp-server-http-streamable:latest into the mcp-server namespace. For the full flow (build → push → deploy), see Deploy to Kubernetes above.

1. Create namespace, deployment, and service:

   kubectl apply -f k8s/
   

   (Numbered filenames ensure the namespace is created before the deployment and service.)

2. Wait for the pod to be ready:

   kubectl -n mcp-server get pods -l app=mcp-server-http-streamable -w
   

   (Ctrl+C when Running and 1/1 ready.)

3. Access the MCP server:

   • NodePort (cluster node IP): The service exposes port 30800 on each node. Use:

     http://<NODE_IP>:30800/mcp
     

     Get a node IP with kubectl get nodes -o wide or, on minikube, minikube ip.

   • Port-forward (any cluster):

     kubectl -n mcp-server port-forward svc/mcp-server-http-streamable 8000:8000
     

     Then use http://localhost:8000/mcp in your MCP client.

4. Clean up:

   kubectl delete -f k8s/
   

Connecting a client

Use the Streamable HTTP URL when adding this server to an MCP client (e.g. Cursor, Claude Desktop):

• URL: http://localhost:8000/mcp (or your host/port if different)

Cursor with uvx: To run the server via uvx from Git in Cursor, add to your MCP config (e.g. ~/.cursor/mcp.json):

{
  "mcpServers": {
    "McpServerHttpStreamable": {
      "command": "/opt/homebrew/bin/uvx",
      "args": [
        "--from",
        "git+https://github.com/douglasqsantos/mcp-server-http-streamable.git",
        "mcp-server"
      ]
    }
  }
}

Start the server from Cursor (or run uvx --from git+https://... mcp-server in a terminal), then use http://localhost:8000/mcp in clients that connect by URL.

Claude Desktop (via mcp-remote)

Claude Desktop talks to MCP servers over stdio by default. To use this HTTP server, run it via mcp-remote, which bridges stdio to your running HTTP server.

1. Start this server (local or Docker) so it is listening on http://localhost:8000/mcp (or your host/port).

2. Edit Claude’s MCP config

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

3. Add a server entry that uses npx and mcp-remote with your server URL and --allow-http:

   {
     "mcpServers": {
       "RemoteExample": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "http://localhost:8000/mcp",
           "--allow-http"
         ]
       }
     }
   }
   

   Use http://0.0.0.0:8000/mcp only if Claude and the server run on the same machine and you intend to bind to all interfaces; otherwise prefer http://localhost:8000/mcp.

4. Restart Claude Desktop. The server’s tools (e.g. greeting) should appear once connected.

5. Use it in chat — In Claude, you can ask in plain language and Claude will call the tool. For example:

   • “Send a greeting to Douglas” → Claude uses the greeting tool with name: "Douglas" and replies with “Hi Douglas”.
   • You can substitute any name: “Say hello to Maria”, “Greet the team”, etc.

Requirements: Node.js (for npx) and the mcp-remote package (installed automatically when you use npx mcp-remote).

Using the MCP Inspector

The MCP Inspector lets you test tools and resources without a full client. Use it with this server as follows.

1. Start the server (in one terminal):

   uv run mcp-server
   

   Leave it running. The server must be up before the inspector connects.

2. Open the MCP Inspector

   • From Cursor: Command Palette (Cmd+Shift+P / Ctrl+Shift+P) → run “MCP: Open Inspector” (or use Settings → MCP and open the inspector from there).
   • From the CLI: Run mcp dev; when prompted for a connection type, choose the option to connect to a remote or Streamable HTTP server (if your CLI supports it).

3. Connect to this server

   • In the inspector UI, add a new connection or “Connect to server”.
   • Choose Streamable HTTP (or “HTTP” / “Remote URL”).
   • Enter the server URL: http://localhost:8000/mcp (use a different host/port if you changed MCP_HOST or MCP_PORT).
   • Confirm or connect.

4. Test the server

   • After connecting, the inspector should list tools (e.g. greeting).
   • Open the greeting tool, set name (e.g. "World"), and run it to see the response.

If the inspector only supports stdio, start the server as above and use another MCP client that supports Streamable HTTP (e.g. Cursor with an MCP server config that uses the http://localhost:8000/mcp URL).

Testing with the server in Kubernetes (via proxy)

When the MCP server is running in the cluster (see Deploy to Kubernetes), you can test it from your machine using the MCP Inspector and a Streamable HTTP connection via proxy.

1. Deploy the server and ensure the pod is running:

   kubectl apply -f k8s/
   kubectl -n mcp-server get pods -l app=mcp-server-http-streamable
   

2. Get the NodePort from the service (our manifest uses 30800):

   kubectl -n mcp-server get svc mcp-server-http-streamable
   

   Note the PORT(S) value (e.g. 8000:30800/TCP) — the second number is the NodePort.

3. Expose the service to localhost (so the inspector can reach it):

   kubectl -n mcp-server port-forward svc/mcp-server-http-streamable 30800:8000
   

   Leave this running. The MCP endpoint is then at http://127.0.0.1:30800/mcp.

4. Open the MCP Inspector (run locally):

   mcp dev
   

   This starts the inspector; the server itself runs in the cluster (step 3).

5. In the inspector, add a new connection:

   • Transport type: Streamable HTTP
   • Connection type: Via proxy (use the proxy option so the inspector connects to the K8s-exposed URL)
   • URL: http://127.0.0.1:30800/mcp (with the port-forward above; if you use the node IP and NodePort instead, use http://<NODE_IP>:30800/mcp and get the node IP with kubectl get nodes -o wide or minikube ip)

6. Connect and test the greeting tool as in the steps above.

Tools

• greeting(name) — Returns a greeting for the given name.

License

MIT License. See LICENSE for details. You may use, copy, modify, and distribute this sample for any purpose.