HTTP Streamable MCP Server

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

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 serv