MCP Server kết nối API bên thứ ba — Weather, Stocks, News cho Claude

Model Context Protocol (MCP) mở ra khả năng kết nối Claude với thế giới bên ngoài thông qua các server cung cấp tools và resources. Một trong những ứng dụng thực tế nhất của MCP là xây dựng server đóng vai trò API gateway, cho phép Claude truy vấn dữ liệu thời gian thực từ các dịch vụ bên thứ ba: thời tiết, giá chứng khoán, tin tức, tỷ giá. Bài viết này hướng dẫn bạn xây dựng MCP Server hoàn chỉnh với xác thực, caching và xử lý lỗi chuyên nghiệp.

MCP Server là gì và tại sao cần API Gateway

MCP Server là một ứng dụng chạy riêng biệt, giao tiếp với Claude thông qua giao thức MCP. Server cung cấp cho Claude các "tools" -- hàm mà Claude có thể gọi khi cần dữ liệu hoặc thực hiện hành động. Khi bạn hỏi Claude "Thời tiết Hà Nội hôm nay thế nào?", Claude sẽ gọi tool get_weather trên MCP Server, server gọi API thời tiết, xử lý kết quả và trả về cho Claude.

Tại sao không để Claude gọi API trực tiếp? Vì nhiều lý do quan trọng:

• Bảo mật: API key được lưu trên server, không cần chia sẻ với Claude.
• Xử lý phức tạp: Server có thể gọi nhiều API, aggregate dữ liệu, format kết quả trước khi trả cho Claude.
• Caching: Tránh gọi API quá nhiều, tiết kiệm chi phí và tăng tốc phản hồi.
• Rate limiting: Kiểm soát số lượng request, tránh bị API provider block.
• Error handling: Xử lý lỗi tập trung, retry logic, fallback strategy.

Kiến trúc MCP Server cho API Gateway

Một MCP Server đóng vai API gateway có kiến trúc gồm các lớp sau:

• Transport Layer: nhận request từ Claude qua stdio hoặc SSE.
• Tool Registry: danh sách tools mà Claude có thể gọi, với schema input/output rõ ràng.
• Authentication Manager: quản lý API keys, OAuth tokens, refresh tokens.
• Cache Layer: lưu kết quả API với TTL (time-to-live) phù hợp.
• Rate Limiter: kiểm soát số request theo thời gian.
• API Clients: các module gọi API bên thứ ba cụ thể.
• Response Formatter: chuẩn hóa dữ liệu trước khi trả cho Claude.

Xử lý xác thực (Authentication)

Mỗi API bên thứ ba có cách xác thực khác nhau. MCP Server cần hỗ trợ nhiều phương thức xác thực và quản lý credentials an toàn.

API Key Authentication

Đây là phương thức đơn giản nhất, dùng cho hầu hết các API public. API key được lưu trong environment variables hoặc file cấu hình mã hóa, không bao giờ hardcode trong source code.

Hướng dẫn tôi thiết kế module authentication cho MCP Server
hỗ trợ nhiều phương thức xác thực:

1. API Key: lưu trong environment variables,
   truyền qua header hoặc query parameter
2. OAuth 2.0: quản lý access token, refresh token,
   tự động refresh khi token hết hạn
3. Bearer Token: token cố định hoặc JWT

Yêu cầu:
- Credentials không được lưu trong source code
- Hỗ trợ file .env cho development và environment
  variables cho production
- Log khi authentication thất bại nhưng không log
  credentials
- Mỗi API provider có cấu hình riêng

Cho tôi cấu trúc code (TypeScript) với ví dụ cho
cả 3 phương thức.

OAuth 2.0 cho API phức tạp

Một số API yêu cầu OAuth 2.0 flow, ví dụ Google APIs hoặc các API banking. MCP Server cần lưu trữ và tự động refresh access token khi hết hạn, đảm bảo Claude luôn có thể truy cập dữ liệu mà không bị gián đoạn.

Chiến lược caching

Caching là yếu tố quyết định hiệu suất và chi phí của MCP Server. Không phải dữ liệu nào cũng cần caching, và TTL cần phù hợp với tính chất dữ liệu.

Thiết kế chiến lược caching cho MCP Server kết nối 3 loại API:

1. Weather API (OpenWeatherMap):
   - Dữ liệu thời tiết hiện tại: cache bao lâu?
   - Dữ liệu dự báo 5 ngày: cache bao lâu?
   - Dữ liệu theo thành phố: cache key như thế nào?

2. Stock API (VN stock market):
   - Giá cổ phiếu: có nên cache không? (real-time vs delayed)
   - Thông tin công ty: cache bao lâu?
   - Lịch sử giao dịch: cache bao lâu?

3. News API (RSS feeds):
   - Tin mới nhất: cache bao lâu?
   - Tin theo chủ đề: cache key như thế nào?

Yêu cầu:
- Chọn giữa in-memory cache (Map/LRU) và Redis
  dựa trên scale
- Cache invalidation strategy: TTL, manual purge,
  event-based
- Xử lý cache miss: gọi API và lưu cache đồng thời
- Memory management: giới hạn cache size, eviction policy
- Metrics: cache hit rate, cache size, memory usage

Cho code mẫu TypeScript cho cache layer.

Xử lý lỗi và Rate Limiting

Khi kết nối với API bên thứ ba, lỗi là điều không thể tránh: API down, rate limit exceeded, timeout, dữ liệu không hợp lệ. MCP Server cần xử lý tất cả các tình huống này một cách graceful.

Error Handling

Thiết kế module xử lý lỗi cho MCP Server với các tình huống:

1. API trả về HTTP 429 (Rate Limited):
   - Retry với exponential backoff
   - Thông báo Claude rằng dữ liệu tạm thời không khả dụng

2. API trả về HTTP 500/503 (Server Error):
   - Retry tối đa 3 lần với delay tăng dần
   - Fallback sang cache cũ nếu có
   - Trả về lỗi rõ ràng cho Claude nếu không thể recover

3. API timeout (không phản hồi sau 10 giây):
   - Cancel request, trả về cache cũ hoặc thông báo lỗi
   - Log để theo dõi tần suất timeout

4. API trả về dữ liệu không hợp lệ:
   - Validate response schema trước khi trả cho Claude
   - Log dữ liệu bất thường để debug

5. API key hết hạn hoặc bị revoke:
   - Phát hiện sớm qua response code
   - Thông báo admin và trả lỗi rõ ràng cho Claude

Cho code mẫu với error classes tùy chỉnh và retry logic.

Rate Limiting

Thiết kế rate limiter cho MCP Server quản lý 3 API providers:

1. OpenWeatherMap (free tier): 60 calls/phút, 1000 calls/ngày
2. VN Stock API: 100 calls/phút, không giới hạn ngày
3. News RSS: không giới hạn nhưng nên throttle 10 calls/phút

Yêu cầu:
- Token bucket algorithm cho mỗi provider
- Queuing: khi vượt rate limit, queue request thay vì reject
- Priority: request từ Claude (user-facing) ưu tiên hơn
  background refresh
- Dashboard: metrics hiển thị usage theo provider
- Alert: thông báo khi usage đạt 80% limit

Cho code mẫu TypeScript.

Ví dụ 1: Weather API MCP Server

Đây là ví dụ đầu tiên và đơn giản nhất: MCP Server kết nối OpenWeatherMap API cho phép Claude truy vấn thời tiết.

Thiết kế Tools

Thiết kế MCP tools cho Weather API Server gồm:

Tool 1: get_current_weather
- Input: city_name (string, required),
         country_code (string, optional, default "VN")
- Output: temperature, humidity, wind_speed, description,
          feels_like, visibility
- Format output dạng text ngắn gọn cho Claude đọc

Tool 2: get_forecast
- Input: city_name (string), days (number, 1-5, default 3)
- Output: array of daily forecasts (date, min_temp, max_temp,
          description, rain_probability)
- Format output dạng bảng

Tool 3: compare_weather
- Input: cities (array of strings, max 5)
- Output: bảng so sánh thời tiết hiện tại giữa các thành phố

Yêu cầu:
- Hỗ trợ tên thành phố tiếng Việt có dấu
  (tự động convert sang tên API hiểu được)
- Đơn vị mặc định: Celsius, km/h
- Cache thời tiết hiện tại 15 phút, forecast 1 giờ
- Xử lý trường hợp thành phố không tồn tại

Cho code TypeScript đầy đủ cho MCP Server sử dụng
@modelcontextprotocol/sdk.

Cấu hình và chạy

Hướng dẫn tôi cấu hình và chạy Weather MCP Server:

1. Đăng ký OpenWeatherMap API key (free tier)
2. Tạo file .env với cấu hình:
   OPENWEATHER_API_KEY=xxx
   CACHE_TTL_CURRENT=900
   CACHE_TTL_FORECAST=3600
3. Cấu hình trong Claude Desktop (claude_desktop_config.json):
   thêm server vào mcpServers
4. Test: hỏi Claude "Thời tiết Đà Nẵng hôm nay thế nào?"
   và verify kết quả
5. Debug: cách xem logs nếu tool không hoạt động

Ví dụ 2: VN Stock API MCP Server

MCP Server kết nối API chứng khoán Việt Nam, cho phép Claude truy vấn giá cổ phiếu, thông tin doanh nghiệp và phân tích kỹ thuật cơ bản.

Thiết kế Tools

Thiết kế MCP tools cho VN Stock API Server:

Tool 1: get_stock_price
- Input: symbol (string, ví dụ "VNM", "FPT", "VIC")
- Output: giá hiện tại, thay đổi (%), khối lượng,
          giá cao nhất/thấp nhất ngày, giá tham chiếu
- Lưu ý: thị trường VN mở 9h-11h30 và 13h-14h45

Tool 2: get_stock_info
- Input: symbol (string)
- Output: tên công ty, ngành, vốn hóa, P/E, EPS,
          dividend yield, mô tả ngắn
- Cache lâu hơn vì ít thay đổi (24 giờ)

Tool 3: get_market_overview
- Input: không có (hoặc market: "HOSE" | "HNX" | "UPCOM")
- Output: VN-Index, HNX-Index, tổng khối lượng giao dịch,
          top tăng, top giảm, top khối lượng

Tool 4: get_stock_history
- Input: symbol (string), period ("1W" | "1M" | "3M" | "1Y")
- Output: dữ liệu OHLCV theo ngày, tính toán SMA20,
          SMA50, RSI cơ bản

Nguồn dữ liệu: sử dụng API công khai từ các trang
như cafef.vn, vndirect, hoặc SSI iBoard.

Cho code TypeScript đầy đủ.

Xử lý đặc thù chứng khoán Việt Nam

Khi xây dựng VN Stock MCP Server, cần xử lý các
đặc thù sau:

1. Giờ giao dịch: chỉ phiên 1 (9h-11h30) và phiên 2
   (13h-14h45). Ngoài giờ này trả về giá đóng cửa
   + thông báo thị trường đã đóng.

2. Phiên ATC (14h30-14h45): giá có thể biến động mạnh,
   cần note cho Claude.

3. Ngày nghỉ lễ Việt Nam: thị trường không mở vào
   Tết Nguyên Đán, 30/4-1/5, 2/9, Giỗ Tổ Hùng Vương.
   Cần có danh sách ngày nghỉ.

4. Mã chứng khoán: 3 ký tự cho HOSE (VNM, FPT),
   3 ký tự cho HNX, hỗ trợ autocomplete.

5. Đơn vị: giá VND, khối lượng bằng cổ phiếu
   (không phải lot).

6. Dữ liệu delayed: nhiều API miễn phí delay 15 phút,
   cần thông báo rõ cho Claude biết dữ liệu là delayed.

Hãy thiết kế logic xử lý các đặc thù này.

Ví dụ 3: News RSS MCP Server

MCP Server đọc và tổng hợp tin tức từ nhiều nguồn RSS feeds, cho phép Claude truy vấn tin mới nhất theo chủ đề.

Thiết kế Tools

Thiết kế MCP tools cho News RSS Server:

Tool 1: get_latest_news
- Input: category ("technology" | "business" | "vietnam"
         | "world" | "sports"), count (number, default 5)
- Output: danh sách bài báo (title, source, published_date,
          summary 2-3 câu, link)

Tool 2: search_news
- Input: query (string), days_back (number, default 7)
- Output: bài báo matching query, sắp xếp theo relevance

Tool 3: get_news_summary
- Input: category (string), period ("today" | "this_week")
- Output: tóm tắt 5-7 câu về các sự kiện nổi bật

Nguồn RSS:
- VnExpress: vnexpress.net/rss
- Tuổi Trẻ: tuoitre.vn/rss
- TechCrunch: feeds.feedburner.com/TechCrunch
- Reuters: reuters.com/rss

Yêu cầu:
- Parse RSS XML thành structured data
- Tóm tắt bài viết (lấy description từ RSS, không cần
  scrape full article)
- Deduplicate: bài giống nhau từ nhiều nguồn chỉ hiển thị 1
- Cache: refresh RSS feed mỗi 15 phút
- Hỗ trợ tin tiếng Việt và tiếng Anh

Cho code TypeScript đầy đủ.

Triển khai MCP Server

Sau khi phát triển xong, bạn cần triển khai MCP Server để sử dụng với Claude Desktop hoặc Claude Code.

Chạy local

Hướng dẫn triển khai MCP Server trên máy local:

1. Cấu trúc dự án:
   mcp-api-gateway/
   ├── src/
   │   ├── index.ts          (entry point)
   │   ├── tools/            (tool definitions)
   │   ├── clients/          (API clients)
   │   ├── cache/            (cache layer)
   │   ├── auth/             (authentication)
   │   └── utils/            (helpers, rate limiter)
   ├── .env                  (API keys)
   ├── package.json
   └── tsconfig.json

2. Build và chạy: npm run build && node dist/index.js
3. Cấu hình trong Claude Desktop:
   {
     "mcpServers": {
       "api-gateway": {
         "command": "node",
         "args": ["/path/to/dist/index.js"],
         "env": {
           "OPENWEATHER_API_KEY": "xxx",
           "STOCK_API_KEY": "xxx"
         }
       }
     }
   }
4. Verify: khởi động lại Claude Desktop, kiểm tra tools
   xuất hiện trong menu

Deploy lên server (cho team sử dụng)

Hướng dẫn deploy MCP Server lên VPS để nhiều người dùng:

1. Chọn transport: SSE (Server-Sent Events) thay vì stdio
   khi deploy remote
2. Thêm HTTP server wrapper (Express/Fastify) với SSE endpoint
3. Bảo mật: HTTPS, API key cho MCP client, CORS config
4. Monitoring: health check endpoint, uptime monitoring
5. Docker: tạo Dockerfile và docker-compose.yml
6. Process management: PM2 hoặc systemd
7. Logging: structured logging (JSON) với rotation
8. Auto-restart: tự khởi động lại khi crash

Cho cấu hình mẫu cho từng bước.

Testing MCP Server

Trước khi deploy, cần test kỹ MCP Server để đảm bảo hoạt động ổn định.

Hướng dẫn tôi viết test cho MCP Server:

1. Unit tests:
   - Test từng API client riêng lẻ (mock HTTP responses)
   - Test cache layer: set, get, TTL expiry, eviction
   - Test rate limiter: allow, reject, queue
   - Test error handling: retry, fallback, timeout

2. Integration tests:
   - Test MCP protocol: tool listing, tool calling
   - Test end-to-end: request -> cache check -> API call
     -> cache store -> response

3. Mocking:
   - Mock API responses cho test offline
   - Mock clock cho TTL tests
   - Mock rate limiter cho stress tests

4. Performance tests:
   - Response time với cache hit vs cache miss
   - Memory usage sau 1000 requests
   - Concurrent request handling

Framework: Vitest hoặc Jest
Cho code mẫu cho 2-3 test cases quan trọng nhất.

Mở rộng: Thêm API mới vào MCP Server

Kiến trúc tốt cho phép thêm API mới một cách dễ dàng. Khi cần kết nối thêm một API bên thứ ba, bạn chỉ cần tạo thêm một API client module và đăng ký tools mới.

Tôi muốn thêm Exchange Rate API vào MCP Server hiện tại.
Hãy hướng dẫn:

1. Tạo API client mới: src/clients/exchangeRate.ts
   - API: exchangerate-api.com hoặc Open Exchange Rates
   - Hàm: getRate(from, to), getMultipleRates(base, targets)

2. Tạo tool mới: src/tools/exchangeRate.ts
   - Tool get_exchange_rate:
     Input: from_currency, to_currency, amount (optional)
     Output: rate, converted amount, last updated

3. Đăng ký tool trong index.ts

4. Cấu hình cache: tỷ giá cache 1 giờ
   (biến động không nhanh bằng stock)

5. Test tool mới

Mỗi bước cho code cụ thể và giải thích cách integrate
vào codebase hiện tại mà không ảnh hưởng tools đã có.

Best Practices khi xây dựng MCP API Gateway

• Một server, nhiều APIs: gom nhiều API vào một MCP Server thay vì tạo nhiều server riêng lẻ. Giúp Claude có cái nhìn tổng thể và kết hợp dữ liệu từ nhiều nguồn.
• Schema rõ ràng: mô tả tool input/output chi tiết bằng JSON Schema. Claude sẽ sử dụng tool chính xác hơn khi schema rõ ràng.
• Format output cho Claude: trả dữ liệu dạng text dễ đọc, không trả JSON thô. Ví dụ: "Nhiệt độ Hà Nội: 28 độ C, Độ ẩm: 75%, Trời nhiều mây" thay vì JSON object.
• Graceful degradation: khi một API down, các tools khác vẫn hoạt động bình thường. Không để lỗi của weather API ảnh hưởng đến stock API.
• Security first: không bao giờ expose API key qua tool response. Validate tất cả input từ Claude trước khi gọi API.
• Logging và monitoring: ghi log mọi API call với response time, status code. Thiết lập alert khi error rate tăng cao.

Bước tiếp theo

Bạn đã nắm được cách xây dựng MCP Server kết nối API bên thứ ba với đầy đủ authentication, caching, error handling và rate limiting. Hãy bắt đầu với một API đơn giản như weather, sau đó mở rộng thêm stock và news. Khi đã quen, bạn có thể kết nối bất kỳ API nào: payment gateways, CRM, ERP hoặc internal APIs của doanh nghiệp. Khám phá thêm hướng dẫn phát triển MCP tại Thư viện Ứng dụng Claude.