MCP - kết nối Claude / Cursor

Model Context Protocol server AstroWay phơi bày tất cả 771 endpoint như công cụ cho AI‑agent. Hai chế độ - cả hai đều được hỗ trợ nguyên bản bởi mọi client 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 newcomers không npm, hoặc khi bạn muốn zero‑install
Stdio (npm)	npx @astroway/mcp	Cursor power users, phát triển cục bộ, privacy‑conscious (khóa không bao giờ rời máy của bạn), offline‑ready

Hosted endpoint và npm‑package sử dụng cùng một danh mục công cụ (được tạo từ một /v1/openapi.json). Auth: cùng một khóa API aw_test_* / aw_live_* - ở hosted được gửi qua header Authorization: Bearer …, ở stdio 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) - không cần cài đặt

Bắt đầu nhanh không cần npm - chọn client của bạn. Trước khi cài đặt, lấy khóa tại api.astroway.info/dashboard/sign-up (10 000 credit/tháng miễn phí).

Cursor (one-click)

Nhấn nút - Cursor sẽ mở, yêu cầu xác nhận, và tự động thêm bản ghi:

Install in Cursor →

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

Cursor không thể chèn secret từ deeplink - trong ~/.cursor/mcp.json sẽ ghi nguyên mẫu Bearer YOUR_API_KEY, mà server sẽ trả về 403 invalid_format.

Sau khi nhấn nút:

1. Cursor Settings (⚙️ góc trên bên phải) → Tools & MCP → tìm astroway-hosted trong danh sách.
2. Nhấn ba chấm (⋯) bên cạnh server → Edit configuration.
3. Trong trường Authorization thay Bearer YOUR_API_KEY bằng Bearer aw_test_… (hoặc aw_live_…) - khóa thực của bạn từ Dashboard.
4. Lưu → mở lại danh sách MCP → chắc chắn trạng thái enabled + chấm xanh + bộ đếm 780+ tools enabled.

Hoặc - chỉnh sửa file trực tiếp: ~/.cursor/mcp.json (headers.Authorization).

Ghi chú

Cursor áp đặt giới hạn độ dài tên: server_name:tool_name ≤ 60 ký tự. Khoảng 90 trong số 780+ công cụ (chủ yếu các nhóm hellenistic_*, psychological_*, zi_wei_*, zodiac_* và numerology_*) bị Cursor lọc và sẽ không khả dụng qua LLM. Các ~690 còn lại hoạt động. Trong Claude Desktop không có giới hạn này - danh mục đầy đủ.

Claude Desktop

Settings → Developer → Edit Config mở claude_desktop_config.json. File này chỉ chạy các lệnh cục bộ: bản ghi với url bị bỏ qua và hiển thị thông báo “Some MCP servers couldn’t be loaded”. Hosted server kết nối qua bridge mcp-remote, cần Node.js:

{
  "mcpServers": {
    "astroway-hosted": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.astroway.info/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer aw_live_..." }
    }
  }
}

Đóng hoàn toàn Claude Desktop (Cmd+Q) và mở lại. Khóa nằm trong env, vì Claude Desktop trên Windows tách đối số tại dấu cách sau Bearer.

Hộp thoại Add custom connector trong Settings → Connectors chỉ nhận tên và URL, không có trường cho header Authorization, vì vậy không thể truyền khóa AstroWay qua đó.

JSON config (manual)

Cho Cursor, Cline, Continue và Windsurf, những cái nhận url từ xa trực tiếp:

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

Đường dẫn tới các config:

• 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 client hoàn toàn (Cmd+Q → mở lại).

Kiểm tra

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

Trong client - yêu cầu: “List 5 AstroWay tool names from 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ần suất

Hosted endpoint được bảo vệ bằng 3 lớp giới hạn: Cloudflare DDoS layer + edge proxy 120 req/min/IP + bucket trong bộ nhớ 60/60s/(IP+key). Các client MCP thực tế (Claude Desktop, Cursor) không gần tới các giới hạn này - chúng không thực hiện burst request. Nếu tự động hoá / CI của bạn cần > 120 req/min - hãy dùng chế độ stdio (không có giới hạn, truy cập trực tiếp qua api.astroway.info/v1/* với rate‑limit theo gói của bạn).

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

Nếu hosted endpoint trả về 5xx, client MCP sẽ gặp lỗi khi gọi tools/list. Điều này không ảnh hưởng tới client stdio - chúng chạy npm‑package cục bộ, truy cập trực tiếp tới api.astroway.info/v1/* mà không qua lớp hosted.

Fallback cho các tích hợp quan trọng: thêm máy chủ MCP thứ hai vào config với chế độ stdio - client sẽ tự động dùng nó nếu hosted không trả lờ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 hosted endpoint có thể xem tại status.astroway.info. Các sự cố > 5 phút được công bố dưới dạng postmortem trong vòng 5 ngày làm việc (theo /sla/).

Stdio (npm) - cho phát triển cục bộ

[@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) - npm‑package, chạy cục bộ như subprocess. Một npm‑package, tích hợp nguyên bản với Claude Desktop, Cursor và bất kỳ client MCP‑tương thích nào.

Cách hoạt động

Danh sách tool được tạo khi build từ live OpenAPI‑spec (api.astroway.info/v1/openapi.json). Mỗi bản phát hành của package tự động bao gồm mọi endpoint mới - không cần bảo trì thủ công.

Mỗi endpoint trở thành một công cụ dạng:

• tools/list trả về mô tả và schema đầu vào (kèm ví dụ body request)
• 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 agent dưới dạng structured JSON

Mỗi bản phát hành còn được ship với SLSA provenance (Sigstore-attested) - đây là bảo chứng rằng npm‑package được xây dựng từ commit trong repo 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. Trong thanh dưới chat sẽ xuất hiện chỉ báo 🛠️ với số lượng tool đã 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

Câu lệnh npx @astroway/mcp vẫn hoạt động trong mọi client MCP‑tương thích. Config giống nhau - chỉ thay đổi đường dẫn file:

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

Client	Path to config
Cline (VS Code)	.cline/mcp.json ở root workspace
Continue	~/.continue/config.json (under mcpServers)
Windsurf	~/.codeium/windsurf/mcp_config.json
GitHub Copilot Chat (VS Code)	preview‑flag → mcp.json trong workspace
VS Code MCP extension	~/.vscode/mcp.json

Các client MCP khác

Chạy như stdio‑server:

ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp

Mẹo

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

Privacy - từ v1.0.0+

Server MCP này không gửi bất kỳ dữ liệu nào trở lại AstroWay ngoại trừ các API‑call mà bạn yêu cầu thực hiện. Không có telemetry, không có analytics, không có công tắc opt‑in/opt‑out - mặc định là im lặng.

Các request outbound mang hai header nhận dạng để backend AstroWay có thể phân biệt traffic MCP với HTTP trực tiếp trong log của mình:

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

Không header nào chứa session ID, machine fingerprint hay bất kỳ thông tin cá nhân nào. Đây là semantics chuẩn của User-Agent - mỗi công cụ CLI gửi thông tin tương tự.

Đăng ký tập con - từ v1.0.0+

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

{
  "env": {
    "ASTROWAY_API_KEY": "aw_live_...",
    "ASTROWAY_TOOL_GROUPS": "western,vedic,relational",   // only these prefixes
    "ASTROWAY_READONLY": "1"                               // skip ai/horoscope/reports (LLM-backed, costs credits)
  }
}

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ộ bộ.

ASTROWAY_READONLY=1 bỏ qua ba nhóm gọi LLM nội bộ (ai, horoscope, reports) - hữu ích khi bạn muốn toán học bản đồ thuần túy mà không tốn credit cho việc sinh văn bản.

Cam kết ổn định - từ v1.0.0+

• Danh mục được đóng băng trong suốt phiên. 780+ tools, 12 prompts, 14 resources được nhúng trong npm‑package đã phát hành tại thời điểm build - không thay đổi khi kết nối. Nếu client của bạn cache tools/list sau lần gọi đầu tiên - nó vẫn chính xác suốt phiên.
• Tool identifiers ổn định trong phạm vi major version. Tên dạng astroway_<group>_<tool> sẽ không được đổi tên hay xóa trong v1.x nếu không có ghi chú deprecation trong CHANGELOG.md và một phiên bản minor song song có sẵn.
• Tool input shape ổn định trong phạm vi minor version. Các ràng buộc (regex, range, enum) được thêm qua các patch; việc thêm trường bắt buộc yêu cầu bump minor.
• Refresh danh mục: cài lại. npm i -g @astroway/mcp@latest (hoặc npx -y @astroway/mcp trong cấu hình của bạn) sẽ kéo bộ hiện tại khi khởi động lần sau.

Ví dụ prompt

Sau khi kết nối server, yêu cầu AI:

Bản đồ sinh

Tính bản đồ sinh của tôi - sinh ngày 15 tháng 3 1990, 14:30, Kyiv. Mô tả Sun, Moon, Ascendant và tìm các khía cạnh gần gũi.

Tránsito

Những transit quan trọng của các hành tinh chậm sẽ rơi vào bản đồ sinh của tôi trong năm 2027?

Claude thực hiện hai tool‑call: đầu tiên transits (ảnh hiện tại), sau đó transit-calendar (khoảng thời gian). Giải thích xu hướng.

Vedic Mahadasha

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

Dùng tool 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 khía cạnh chéo mạnh nhất là gì?

synastry tool với hai khối chart + giải thích điểm tương hợp.

Tarot

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

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

Danh sách tất cả các tool

Sau khi kết nối, 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
# (starts the stdio server; tool-list calls come from the MCP client over the protocol)

Cấu hình

Variable	Default	Description	Since version
ASTROWAY_API_KEY	(bắt buộc)	Live: aw_live_.... Sandbox: aw_test_....	0.1.0
ASTROWAY_BASE_URL	https://api.astroway.info/v1	Override cho môi trường self‑hosted/staging.	0.1.0
ASTROWAY_TOOL_GROUPS	(tất cả nhóm)	Các tiền tố ngăn cá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 hỗ trợ LLM (ai, horoscope, reports).	1.0.0
LOG_LEVEL	error	silent/error/warn/info/debug - cấp độ log trên stderr.	0.8.0
LOG_FILE	(không ghi)	Đường dẫn tới file để sao chép log.	0.8.0
MCP_FLAT_TOOLS	0	1 trả về tên phẳng pre‑v0.9 (chart thay vì astroway_western_chart). Legacy.	0.9.0

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

LLM chung (không grounding) sẽ nói “vào tháng 7 nào đó Saturn sẽ tạo tam giác với Jupiter của bạn” - không có ngày chính xác, lệch ±15 ngày. MCP‑agent thực hiện tool_use POST /v1/transits và trả về UTC‑timestamp đến giây, dựa trên Swiss Ephemeris thực.

Lợi thế không phải ở LLM, mà ở đảm bảo rằng toán học là thực tế - không phải bịa đặt.

Phân phối package

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

Liên kết

• 📦 npm: npmjs.com/package/@astroway/mcp
• 📘 API docs: /docs/api/
• 🔑 Sign up: /dashboard/sign-up
• 💰 Pricing: /pricing/
• 🌐 Public repo (MIT): github.com/astroway/astroway-mcp