# 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ả {siteMeta.endpoints} đầ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](https://github.com/astroway/astroway-mcp) · npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) · hosted: [mcp.astroway.info/health](https://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](https://api.astroway.info/dashboard/sign-up) (**10.000 tín dụng/tháng miễn phí**).
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 →
:::caution[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](https://api.astroway.info/dashboard/keys).
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`).
:::
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.
Dành cho Cline / Continue / Windsurf hoặc phiên bản cũ của Claude Desktop / Cursor:
```json
{
"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
```bash
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`:
```json
{
"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](https://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/](/sla/)).
## Stdio (npm) — dành cho phát triển cục bộ
[`@astroway/mcp`](https://www.npmjs.com/package/@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](https://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/` 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](https://search.sigstore.dev/)) — đả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`:
```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`:
```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:
```json
{
"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:
```bash
ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp
```
## 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/ (Node/)`
- `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:
```jsonc
{
"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__` 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:
```bash
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](https://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](https://github.com/punkpeye/awesome-mcp-servers/pull/5972)
## Liên kết
- 📦 npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp)
- 📘 Tài liệu API: [/docs/api/](/docs/api/)
- 🔑 Đăng ký: [/dashboard/sign-up](/dashboard/sign-up)
- 💰 Bảng giá: [/pricing/](/pricing/)
- 🌐 Kho công khai (MIT): [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)