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.

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:

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

Environment variables (optional):

Example with a custom port:

Option 2: Docker

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

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

Option 3: Docker Compose

Build and start the service (foreground):

Run in the background:

Stop:

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

Option 4: 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)

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 server.py

   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 server.py

   This starts the inspector; the local server.py is only used to launch the inspector process.

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.