MCP — kết nối Claude / Cursor

Máy chủ giao thức Mô hình Ngữ cảnh (MCP) của AstroWay hiển thị tất cả 723 đầu cuối dưới dạng công cụ cho tác nhân AI. Có hai chế độ — cả hai đều được hỗ trợ nguyên bản bởi tất cả các máy khách tương thích MCP.

Chế độ	URL / lệnh	Khi nào chọn
Hosted HTTP	https://mcp.astroway.info/mcp	Claude Web (claude.ai trong trình duyệt), Claude Desktop / Cursor / Code cho người mới bắt đầu không có npm, hoặc khi bạn muốn cài đặt zero-install
Stdio (npm)	npx @astroway/mcp	Người dùng Cursor nâng cao, phát triển cục bộ, quan tâm đến quyền riêng tư (khóa không bao giờ rời khỏi máy của bạn), sẵn sàng offline

Điểm cuối hosted và gói npm sử dụng cùng danh mục công cụ (được tạo từ cùng một /v1/openapi.json). Xác thực: cùng một khóa API aw_test_* / aw_live_* — trên hosted được gửi qua Authorization: Bearer … header, trên stdio thông qua biến môi trường ASTROWAY_API_KEY.

Nguồn: github.com/astroway/astroway-mcp · npm: npmjs.com/package/@astroway/mcp · hosted: mcp.astroway.info/health

Hosted (mcp.astroway.info) — cài đặt không cần npm

Khởi động nhanh không cần npm — chọn máy khách của bạn. Trước khi cài đặt, hãy lấy khóa của bạn tại api.astroway.info/dashboard/sign-up (10.000 tín dụng/tháng miễn phí).

Cursor (one-click)

Nhấp vào nút — Cursor sẽ mở ra, yêu cầu xác nhận, tự động thêm mục:

Cài đặt trong Cursor →

Bước 2 bắt buộc — nếu không sẽ không hoạt động

Cursor không thể thay thế bí mật từ deeplink — trong ~/.cursor/mcp.json sẽ ghi tạm Bearer YOUR_API_KEY, khiến máy chủ trả về 403 invalid_format.

Sau khi nhấp vào nút:

1. Cài đặt Cursor (⚙️ góc trên bên phải) → Công cụ & MCP → tìm astroway-hosted trong danh sách.
2. Nhấp vào ba dấu chấm (⋯) bên cạnh máy chủ → Chỉnh sửa cấu hình.
3. Trong trường Authorization, thay Bearer YOUR_API_KEY bằng Bearer aw_test_… (hoặc aw_live_…) — khóa thực tế của bạn từ Bảng điều khiển.
4. Lưu → mở lại danh sách MCP → đảm bảo trạng thái enabled + dấu chấm xanh + bộ đếm 630 tools enabled.

Ngoài ra, bạn có thể chỉnh sửa tệp trực tiếp: ~/.cursor/mcp.json (headers.Authorization).

Ghi chú

Cursor giới hạn độ dài tên: server_name:tool_name ≤ 60 ký tự. Khoảng 50 trong số 630 công cụ (các nhóm hellenistic_brennan_*, psychological_modern_*, numerology_kabbalistic_strict_*) bị Cursor lọc và sẽ không khả dụng qua LLM. Khoảng 580 công cụ khác hoạt động. Claude Desktop không có giới hạn này — toàn bộ danh mục.

Claude Desktop (giao diện)

Không cần chỉnh sửa JSON. Trong bất kỳ cuộc trò chuyện nào của Claude Desktop:

1. Nhấp vào + bên trái trường nhập → chọn “Thêm kết nối” trong menu.
2. Trong hộp thoại, chọn “Thêm kết nối tùy chỉnh”.
3. Tên: astroway-hosted
4. URL: https://mcp.astroway.info/mcp
5. Mở rộng “Cài đặt nâng cao” → trong “Tiêu đề tùy chỉnh”, thêm:
   • Khóa: Authorization
   • Giá trị: Bearer aw_live_... (khóa của bạn)
6. Thêm → tìm astroway-hosted trong danh sách Kết nối, bật công tắc.

Không cần khởi động lại Claude Desktop. Nhấp vào + trong cuộc trò chuyện mới — astroway-hosted sẽ xuất hiện trong Kết nối với tất cả 630 công cụ + 12 lời nhắc + 14 tài nguyên.

Cấu hình JSON (thủ công)

Dành cho Cline / Continue / Windsurf hoặc phiên bản cũ của Claude Desktop / Cursor:

{
  "mcpServers": {
    "astroway-hosted": {
      "url": "https://mcp.astroway.info/mcp",
      "headers": {
        "Authorization": "Bearer aw_live_..."
      }
    }
  }
}

Đường dẫn đến tệp cấu hình:

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Cursor: ~/.cursor/mcp.json (toàn cục) hoặc .cursor/mcp.json (trong workspace)
• Cline (VS Code): .cline/mcp.json trong workspace
• Continue: ~/.continue/config.json (khối mcpServers)
• Windsurf: ~/.codeium/windsurf/mcp_config.json

Sau khi chỉnh sửa, khởi động lại hoàn toàn máy khách (Cmd+Q → mở lại).

Kiểm tra

curl https://mcp.astroway.info/health
# {"status":"ok","version":"…","uptime_sec":…,"mcp_protocol_version":"2024-11-05"}

Trong máy khách — hãy yêu cầu: “List 5 tên công cụ AstroWay từ astroway-hosted”. Nó sẽ trả về các tên như astroway_western_chart, astroway_horoscope_daily, astroway_vedic_panchang_full, …

Giới hạn tốc độ

Điểm cuối hosted được bảo vệ bởi giới hạn 3 lớp: Cloudflare chống DDoS + nginx 120 req/phút/IP + bộ nhớ đệm trong bộ nhớ 60/60s/(IP+khóa). Các máy khách MCP thực tế (Claude Desktop, Cursor) không đạt đến những giới hạn này — chúng không thực hiện các yêu cầu burst. Nếu tự động hóa/CI của bạn cần > 120 req/phút — hãy sử dụng chế độ stdio (không có giới hạn, kết nối trực tiếp tới api.astroway.info/v1/* theo giới hạn gói cước của bạn).

Nếu mcp.astroway.info tạm thời không khả dụng

Nếu điểm cuối hosted trả về 5xx, máy khách MCP sẽ thấy lỗi khi gọi tools/list. Điều này không ảnh hưởng đến máy khách stdio — chúng chạy gói npm cục bộ, kết nối trực tiếp tới api.astroway.info/v1/* mà không qua lớp hosted trung gian.

Fallback cho tích hợp quan trọng: Thêm máy chủ MCP thứ hai trong cấu hình ở chế độ stdio — máy khách sẽ tự động sử dụng nó nếu hosted không phản hồi tools/list:

{
  "mcpServers": {
    "astroway": {
      "url": "https://mcp.astroway.info/mcp",
      "headers": { "Authorization": "Bearer aw_live_..." }
    },
    "astroway-fallback": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": { "ASTROWAY_API_KEY": "aw_live_..." }
    }
  }
}

Thời gian hoạt động thực tế của điểm cuối hosted có thể xem tại status.astroway.info. Sự cố > 5 phút sẽ được đăng tải dưới dạng postmortem trong vòng 5 ngày làm việc (theo /sla/).

Stdio (npm) — dành cho phát triển cục bộ

@astroway/mcp — gói npm chạy dưới dạng tiến trình con cục bộ. Một gói npm, tích hợp nguyên bản với Claude Desktop, Cursor và bất kỳ máy khách MCP nào.

Cách thức hoạt động

Danh mục công cụ được tạo tại thời điểm build từ đặc tả OpenAPI trực tiếp (api.astroway.info/v1/openapi.json). Mỗi phiên bản của gói tự động cập nhật tất cả các điểm cuối mới — không cần bảo trì thủ công.

Mỗi điểm cuối trở thành một công cụ dạng:

• tools/list trả về mô tả và lược đồ đầu vào (với ví dụ về thân yêu cầu)
• tools/call thực hiện HTTP POST tới https://api.astroway.info/v1/<path> với ASTROWAY_API_KEY của bạn
• Phản hồi được trả về cho tác nhân dưới dạng JSON có cấu trúc

Mỗi phiên bản còn được đóng gói kèm SLSA provenance (được chứng thực bởi Sigstore) — đảm bảo rằng gói npm được xây dựng chính xác từ commit trong kho công khai.

Cài đặt

Claude Desktop (macOS)

Thêm vào ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": {
        "ASTROWAY_API_KEY": "aw_live_..."
      }
    }
  }
}

Khởi động lại Claude Desktop. Biểu tượng 🛠️ sẽ xuất hiện dưới thanh trò chuyện với số lượng công cụ đã tải.

Cursor

Thêm vào ~/.cursor/mcp.json:

{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": { "ASTROWAY_API_KEY": "aw_live_..." }
    }
  }
}

Cline / Continue / Windsurf / Copilot / VS Code MCP

Lệnh npx @astroway/mcp hoạt động trên mọi máy khách tương thích MCP. Cấu hình giống nhau — chỉ thay đổi đường dẫn tệp:

{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": { "ASTROWAY_API_KEY": "aw_live_..." }
    }
  }
}

Máy khách	Đường dẫn đến tệp cấu hình
Cline (VS Code)	.cline/mcp.json trong thư mục gốc workspace
Continue	~/.continue/config.json (trong mcpServers)
Windsurf	~/.codeium/windsurf/mcp_config.json
GitHub Copilot Chat (VS Code)	cờ preview → mcp.json trong workspace
VS Code MCP extension	~/.vscode/mcp.json

Máy khách MCP khác

Chạy dưới dạng máy chủ stdio:

ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp

Mẹo

Lấy khóa của bạn tại api.astroway.info/dashboard/sign-up. Gói miễn phí — 10 000 tín dụng/tháng, không cần thẻ tín dụng.

Bảo mật — từ phiên bản v1.0.0+

Máy chủ MCP này không gửi bất cứ điều gì trở lại AstroWay ngoài các lệnh gọi API mà bạn yêu cầu nó thực hiện. Không có bất kỳ telemetry, analytics nào, không có tùy chọn opt-in/opt-out — yên tĩnh theo mặc định.

Các yêu cầu đầu ra mang theo hai tiêu đề nhận dạng để backend của AstroWay có thể phân biệt lưu lượng MCP khỏi HTTP trực tiếp trong nhật ký của chính nó:

• User-Agent: astroway-mcp/<version> (Node/<node-version>)
• X-Astroway-Channel: mcp

Không có tiêu đề nào trong số này chứa session ID, dấu vân tay máy hay bất kỳ thông tin cá nhân nào. Đây là ngữ nghĩa tiêu chuẩn của User-Agent — mỗi công cụ CLI đều gửi thông tin tương tự.

Đăng ký tập con — từ phiên bản v1.0.0+

Nếu bạn chỉ sử dụng một phần danh mục — hãy đăng ký tập con để cửa sổ ngữ cảnh của LLM vẫn gọn gàng:

{
  "env": {
    "ASTROWAY_API_KEY": "aw_live_...",
    "ASTROWAY_TOOL_GROUPS": "western,vedic,relational",   // chỉ những tiền tố này
    "ASTROWAY_READONLY": "1"                               // bỏ qua nhóm ai/horoscope/reports (sử dụng LLM, tốn tín dụng)
  }
}

Các nhóm phổ biến: western, vedic, tarot, numerology, hd (Human Design), relational (synastry/composite/davison), prognostics (transits/progressions/returns), aspects, horary, geo, chinese, bazi, mayan, iching, runes, geomancy. Chạy npx @astroway/mcp --list-tools để xem toàn bộ danh sách.

ASTROWAY_READONLY=1 bỏ qua ba nhóm sử dụng nội bộ LLM (ai, horoscope, reports) — hữu ích khi bạn muốn tính toán bản đồ xác định thuần túy mà không tốn tín dụng cho việc tạo văn bản.

Cam kết ổn định — từ phiên bản v1.0.0+

• Danh mục được đóng băng trong suốt phiên làm việc. 624 công cụ, 12 lời nhắc, 14 tài nguyên được nhúng vào gói npm đã xuất bản tại thời điểm build — không thay đổi trong suốt quá trình kết nối. Nếu máy khách của bạn lưu vào bộ nhớ đệm tools/list sau lần gọi đầu tiên, nó vẫn chính xác trong suốt phiên.
• Định danh công cụ ổn định trong cùng phiên bản major. Tên dưới dạng astroway_<group>_<tool> sẽ không bị đổi tên hay xóa bỏ trong v1.x mà không có ghi chú ngừng hỗ trợ trong CHANGELOG.md và khả năng truy cập song song tối thiểu trong minor tiếp theo.
• Hình dạng đầu vào công cụ ổn định trong cùng phiên bản minor. Việc siết chặt (regex, range, enum) đến trong các bản vá; việc thêm trường bắt buộc yêu cầu tăng minor.
• Làm mới danh mục — cài đặt lại. npm i -g @astroway/mcp@latest (hoặc lệnh npx -y @astroway/mcp trong cấu hình của bạn) sẽ cập nhật danh sách hiện tại vào lần khởi động tiếp theo.

Ví dụ lời nhắc

Sau khi kết nối máy chủ, hãy yêu cầu AI:

Bản đồ natal

Tính bản đồ natal của tôi — sinh ngày 15 tháng 3 năm 1990, 14:30, Kyiv. Mô tả Mặt Trời, Mặt Trăng, Ascendant và tìm các aspect chặt.

Claude sẽ gọi công cụ chart với tham số của bạn, nhận JSON có cấu trúc, và mô tả bản đồ bằng lời.

Chuyển dịch

Những chuyển dịch quan trọng của các hành tinh chậm sẽ xảy ra trên bản đồ natal của tôi trong năm 2027?

Claude thực hiện hai lệnh gọi công cụ: đầu tiên transits (ảnh chụp hiện tại), sau đó transit-calendar (phạm vi). Giải thích các xu hướng.

Vedic Mahadasha

Chạy Vimshottari Mahadasha cho người sinh ngày 22.07.1985 06:45 tại Mumbai. Hiện tại người này đang ở trong giai đoạn nào?

Qua công cụ vedic/dashas/vimshottari/maha — timestamp UTC chính xác của giai đoạn hiện tại.

Synastry

So sánh hai bản đồ: A — 10.06.1988 09:15 London, B — 22.11.1991 22:40 Berlin. Những aspect chéo mạnh nhất là gì?

Công cụ synastry với hai khối chart + giải thích điểm số tương thích.

Tarot

Rút ba lá Rider-Waite-Smith: Quá khứ — Hiện tại — Tương lai. Câu hỏi: “có nên chấp nhận công việc mới không?”. Seed = 42.

tarot/rider-waite/spread với seed cố định để có thể tái tạo.

Danh sách tất cả công cụ

Sau khi kết nối, hãy hỏi Claude:

Liệt kê tất cả các công cụ AstroWay.

Hoặc từ dòng lệnh:

ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1
# (khởi chạy máy chủ stdio; các lệnh gọi danh sách công cụ giao thức được thực hiện bởi máy khách MCP)

Cấu hình

Biến	Mặc định	Mô tả	Từ phiên bản
ASTROWAY_API_KEY	(bắt buộc)	Live: aw_live_.... Sandbox: aw_test_....	0.1.0
ASTROWAY_BASE_URL	https://api.astroway.info/v1	Ghi đè cho môi trường self-hosted/staging.	0.1.0
ASTROWAY_TOOL_GROUPS	(tất cả nhóm)	Danh sách tiền tố được phân tách bằng dấu phẩy để giới hạn danh mục (western,vedic,relational).	1.0.0
ASTROWAY_READONLY	0	1 bỏ qua các nhóm sử dụng LLM (ai, horoscope, reports).	1.0.0
LOG_LEVEL	error	silent/error/warn/info/debug — mức ghi log vào stderr.	0.8.0
LOG_FILE	(không ghi)	Đường dẫn đến tệp để ghi log.	0.8.0
MCP_FLAT_TOOLS	0	1 trả về tên công cụ phẳng cũ (pre-v0.9) (chart thay vì astroway_western_chart). Legacy.	0.9.0

Tại sao MCP chứ không phải tích hợp trực tiếp

LLM tổng quát (không có grounding) sẽ nói “vào khoảng tháng 7, Sao Thổ sẽ hình thành tam giác với Sao Mộc của bạn” — không có ngày chính xác, lệch ±15 ngày. Tác nhân MCP thực hiện tool_use POST /v1/transits và trả về timestamp UTC đến từng giây, dựa trên Swiss Ephemeris thực.

Ưu điểm không phải ở LLM, mà ở đảm bảo rằng phép toán là thực tế — không bịa đặt.

Phân phối gói

• mcp.so listing: mcp.so/server/astroway-mcp/astroway
• mcpservers.org: đang chờ phê duyệt (tính đến tháng 5 năm 2026)
• awesome-mcp-servers (punkpeye): PR #5972

Liên kết

• 📦 npm: npmjs.com/package/@astroway/mcp
• 📘 Tài liệu API: /docs/api/
• 🔑 Đăng ký: /dashboard/sign-up
• 💰 Bảng giá: /pricing/
• 🌐 Kho công khai (MIT): github.com/astroway/astroway-mcp