Máy chủ MCP: Sử dụng AstroAPI từ các trợ lý AI

AstroAPI cung cấp một máy chủ Model Context Protocol (MCP) được lưu trữ sẵn. Kết nối nó với một trợ lý AI như Claude Code, Claude Desktop hoặc Cursor, và trợ lý có thể gọi AstroAPI trực tiếp — tra cứu nơi sinh, tính toán bản đồ sao và giải thích kết quả bằng ngôn ngữ dễ hiểu.

Đây cũng là cách nhanh nhất để xây dựng một tích hợp: kết nối máy chủ MCP với trợ lý lập trình AI của bạn và yêu cầu nó viết mã tích hợp cho bạn. Trợ lý có thể thực hiện các lệnh gọi API thật trong khi làm việc, nên nó thấy được phản hồi thực tế thay vì phải đoán.

Không cần viết mã

Sau khi kết nối, bạn chỉ cần hỏi trợ lý những câu như "Tính bản đồ sao khai sinh cho một người sinh ngày 15 tháng 6 năm 1990 lúc 14:30 tại Amsterdam" — trợ lý sẽ xác định vị trí, gọi API và tóm tắt kết quả.

---

Endpoint

https://mcp.astroapi.cloud/mcp

• Giao thức truyền tải: Streamable HTTP
• Xác thực: khóa AstroAPI thông thường của bạn, được gửi trong header X-Api-Key
• Các module, giới hạn tốc độ và hạn mức của gói đăng ký của bạn được áp dụng chính xác như khi gọi API trực tiếp.

Bạn có thể tạo khóa API trong bảng điều khiển tại mục API Keys. Xem Xác thực để biết chi tiết.

---

Kết nối Claude Code

Chạy lệnh này một lần trong terminal của bạn:

claude mcp add --transport http astroapi https://mcp.astroapi.cloud/mcp \
  --header "X-Api-Key: YOUR_API_KEY"

Sau đó chỉ cần yêu cầu Claude Code sử dụng AstroAPI — ví dụ: "Dùng các công cụ astroapi để tính bản đồ sao khai sinh cho 1990-06-15 14:30 tại Amsterdam và tạo cho tôi một React component hiển thị nó."

Kết nối Cursor

Thêm đoạn sau vào .cursor/mcp.json trong dự án của bạn (hoặc ~/.cursor/mcp.json để áp dụng toàn cục):

{
  "mcpServers": {
    "astroapi": {
      "url": "https://mcp.astroapi.cloud/mcp",
      "headers": {
        "X-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

Kết nối các MCP client khác

Bất kỳ client nào hỗ trợ MCP qua Streamable HTTP với header tùy chỉnh đều hoạt động. Cấu hình:

Cài đặt	Giá trị
URL	https://mcp.astroapi.cloud/mcp
Giao thức truyền tải	Streamable HTTP
Header	X-Api-Key: YOUR_API_KEY

Client được lưu trữ không hỗ trợ header tùy chỉnh

Một số client được lưu trữ (chẳng hạn các web connector của claude.ai) không thể gửi header tùy chỉnh và yêu cầu OAuth. Hỗ trợ OAuth đang nằm trong lộ trình phát triển; hiện tại, hãy dùng một client hỗ trợ header tùy chỉnh, như Claude Code, Claude Desktop hoặc Cursor.

---

Các công cụ có sẵn

Công cụ	Chức năng
astro_resolve_place	Tra cứu tên địa điểm và trả về tọa độ cùng múi giờ IANA. Các trợ lý được hướng dẫn gọi công cụ này trước tiên, để không bao giờ phải đoán tọa độ.
astro_natal_chart	Tính bản đồ sao khai sinh (các điểm, các cung nhà, các góc chiếu), tùy chọn kèm văn bản luận giải, và trả về một bản tóm tắt gọn gàng, dễ đọc.

Nhiều công cụ khác (quá cảnh, so sánh bản đồ đôi, độ tương hợp, pha Mặt Trăng, hình ảnh bản đồ sao và hơn thế nữa) đang được phát triển. Tính khả dụng của công cụ phụ thuộc vào các module trong gói đăng ký của bạn: một công cụ không nằm trong gói của bạn sẽ trả về một thông báo rõ ràng thay vì dữ liệu.

---

Phiên làm việc mẫu

Một cuộc trò chuyện với trợ lý đã kết nối có thể diễn ra như sau:

Bạn: Cung Mặt Trời và cung Mọc của một người sinh ngày 3 tháng 3 năm 1985 lúc 6:45 tại Barcelona là gì?

Trợ lý: gọi astro_resolve_place với "Barcelona", sau đó gọi astro_natal_chart với tọa độ và múi giờ đã xác định — Mặt Trời ở cung Song Ngư tại 12°41′ trong nhà thứ 1, và cung Mọc là Bảo Bình 28°10′ …

Trợ lý đảm nhận việc mã hóa địa lý, chuyển đổi múi giờ và gọi API — những việc thường dễ sai sót khi nhập dữ liệu ngày sinh thủ công.

---

Bước tiếp theo

• Xác thực — tạo và quản lý khóa API
• Bắt đầu — những kiến thức API cơ bản đằng sau các công cụ này
• Bản đồ sao khai sinh — kết quả trả về của phép tính bản đồ sao khai sinh