Build MCP Server từ Scratch — Day 3: SSE Transport & Docker Deployment

Hiện tại MCP server của chúng ta chỉ chạy localhost qua stdio. Claude Desktop launch server như child process, chúng nói chuyện qua stdin/stdout — ổn nếu bạn chỉ dùng một máy.

Nhưng production MCP servers cần remote. Bạn muốn một MCP server phục vụ nhiều agents/users cùng lúc. Deploy lên VPS, Docker, K8s. Có health checks, restart policies, log aggregation.

Cần chuyển từ stdio sang SSE (Server-Sent Events) transport.

SSE Transport Flow#

1
Client              Server (Express.js)
2
  │                      │
3
  ├── GET /sse ─────────►│  Mở SSE stream
4
  │                      ├── event: endpoint /messages?sessionId=xxx
5
  │◄═════════════════════┤  Push events qua stream
6
  │                      │
7
  ├── POST /messages ───►│  Gửi JSON-RPC message
8
  │   ?sessionId=xxx     │
9
  │◄── SSE: result ──────┤  Response qua stream

Client mở GET /sse → server giữ connection open
Server gửi endpoint event với session ID
Client POST JSON-RPC lên /messages?sessionId=xxx
Server push response qua SSE stream

Cài Đặt#

1
cd github-issue-mcp
2
npm install express
3
npm install -D @types/express

SSE Server Module#

src/sse-server.ts — quản lý transport lifecycle cho nhiều concurrent clients:

1
import express from "express";
2
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
3
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
4

5
export function createSSEServer(mcpServer: McpServer, port: number = 3001) {
6
  const app = express();
7
  const transports: Map<string, SSEServerTransport> = new Map();
8

9
  // ──── SSE endpoint ────
10
  app.get("/sse", async (req, res) => {
11
    const transport = new SSEServerTransport("/messages", res);
12
    transports.set(transport.sessionId, transport);
13

14
    res.on("close", () => {
15
      transports.delete(transport.sessionId);
16
      console.error(`[SSE] Closed: ${transport.sessionId}`);
17
    });
18

19
    await mcpServer.connect(transport);
20
  });
21

22
  // ──── Message endpoint ────
23
  app.post("/messages", express.json(), async (req, res) => {
24
    const sessionId = req.query.sessionId as string;
25
    const transport = transports.get(sessionId);
26
    if (!transport) {
27
      res.status(404).json({ error: "Session not found" });
28
      return;
29
    }
30
    await transport.handlePostMessage(req, res);
31
  });
32

33
  // ──── Health check ────
34
  app.get("/health", (req, res) => {
35
    res.json({ status: "ok", uptime: process.uptime(), activeConnections: transports.size });
36
  });
37

38
  return app.listen(port, () => {
39
    console.error(`✅ MCP SSE server on port ${port}`);
40
    console.error(`   SSE: http://localhost:${port}/sse`);
41
  });
42
}

Giải thích:

GET /sse: Client mở kết nối HTTP long-lived. SSEServerTransport giữ response object để push events.
POST /messages: Client gửi JSON-RPC. sessionId query param route đến đúng transport.
Session management: Map<sessionId, transport>. Khi client disconnect, close event cleanup.
GET /health: Cho Docker HEALTHCHECK.

Entry Point (src/server.ts)#

Tương tự src/index.ts từ Day 1+2 nhưng gọi createSSEServer(server, PORT) thay vì StdioServerTransport.

Build & Test#

1
npm run build
2
export GITHUB_TOKEN="ghp_your_token_here"
3
node build/server.js

Health check:#

1
curl http://localhost:3001/health
2
# {"status":"ok","uptime":5.23,"activeConnections":0,"serverName":"github-issue-manager"}

Inspector over SSE:#

1
npx @modelcontextprotocol/inspector -e http://localhost:3001/sse

Raw SSE test (2 terminals):#

Terminal 1:

1
curl -N http://localhost:3001/sse
2
# event: endpoint
3
# data: /messages?sessionId=abc123

Terminal 2:

1
curl -X POST "http://localhost:3001/messages?sessionId=abc123" \
2
  -H "Content-Type: application/json" \
3
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Terminal 1 sẽ nhận response event — đây là cách Claude Desktop giao tiếp với MCP server.

Docker#

Dockerfile (multi-stage):#

1
FROM node:20-alpine AS builder
2
WORKDIR /app
3
COPY package.json tsconfig.json ./
4
RUN npm ci && npm run build && npm prune --production
5

6
FROM node:20-alpine
7
WORKDIR /app
8
RUN addgroup -S mcp && adduser -S mcp -G mcp
9
COPY --from=builder /app/build ./build
10
COPY --from=builder /app/node_modules ./node_modules
11
USER mcp
12
ENV PORT=3001
13
EXPOSE 3001
14
HEALTHCHECK CMD wget --spider http://localhost:3001/health || exit 1
15
CMD ["node", "build/server.js"]

Build & run:#

1
docker build -t github-issue-mcp .
2
docker run -d -p 3001:3001 -e GITHUB_TOKEN="ghp_..." github-issue-mcp

Docker Compose:#

1
services:
2
  mcp-server:
3
    build: .
4
    ports:
5
      - "127.0.0.1:3001:3001"
6
    environment:
7
      - GITHUB_TOKEN=${GITHUB_TOKEN}
8
    restart: unless-stopped
9
    read_only: true

Connect Claude Desktop từ xa#

1
{
2
  "mcpServers": {
3
    "github-issue-manager": {
4
      "type": "sse",
5
      "url": "https://mcp.example.com/sse"
6
    }
7
  }
8
}

Restart Claude Desktop → hammer icon → tools/resources/prompts available over network.

Kết Quả#

Server giờ chạy trên HTTP, có health check, Docker multi-stage build (150MB → 120MB final image), hỗ trợ nhiều concurrent clients.

Day	Chủ đề	Status
1	Setup & Architecture	✅
2	Resources, Prompts & Advanced Tools	✅
3	SSE Transport & Docker	✅ Done
4	Authentication & Production Hardening	Next
5	Testing, Publishing & Ecosystem	—

Series: Building an MCP Server from Scratch. Day 3: SSE transport và Docker deployment.