# MCP — koneksi Claude / Cursor Server **AstroWay MCP** mengekspos **semua {siteMeta.endpoints} endpoint** sebagai alat untuk agen AI. Dua mode didukung secara asli oleh semua klien yang kompatibel dengan MCP. | Mode | URL / perintah | Kapan memilih | |---|---|---| | **Hosted HTTP** | `https://mcp.astroway.info/mcp` | Claude Web (claude.ai di browser), Claude Desktop / Cursor / Code untuk pemula tanpa npm, atau jika ingin instalasi nol | | **Stdio (npm)** | `npx @astroway/mcp` | Pengguna power Cursor, pengembangan lokal, privacy-conscious (kunci tidak pernah meninggalkan mesinmu), siap offline | Endpoint hosted dan paket npm menggunakan **katalog alat yang sama** (dihasilkan dari `/v1/openapi.json` yang sama). Autentikasi: kunci API `aw_test_*` / `aw_live_*` yang sama — pada hosted dikirim melalui header `Authorization: Bearer …`, pada stdio melalui variabel lingkungan `ASTROWAY_API_KEY`. Source: [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`) — instalasi nol Mulai dengan cepat tanpa npm — pilih klienmu. Sebelum menginstal, ambil kunci di [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up) (10.000 kredit/bulan gratis). Klik tombol — Cursor akan terbuka, meminta konfirmasi, dan menambahkan catatan secara otomatis: Install in Cursor → :::caution[Langkah kedua wajib — jika tidak, tidak akan berfungsi] Cursor tidak dapat menyisipkan rahasia dari deeplink — di `~/.cursor/mcp.json` akan tertulis literal `Bearer YOUR_API_KEY`, yang menyebabkan server merespons `403 invalid_format`. **Setelah mengklik tombol:** 1. **Cursor Settings** (⚙️ pojok kanan atas) → **Tools & MCP** → temukan `astroway-hosted` dalam daftar. 2. Klik tiga titik (`⋯`) di samping server → **Edit configuration**. 3. Di bidang `Authorization`, ganti `Bearer YOUR_API_KEY` dengan `Bearer aw_test_…` (atau `aw_live_…`) — kunci API sesungguhnmu dari [Dashboard](https://api.astroway.info/dashboard/keys). 4. Simpan → buka lagi daftar MCP → pastikan status **enabled** + titik hijau + penghitung `630 tools enabled`. Atau, edit file secara langsung: `~/.cursor/mcp.json` (`headers.Authorization`). ::: Tanpa mengedit JSON. Di obrolan Claude Desktop mana pun: 1. Klik **`+`** di sebelah kiri bidang masukan → pilih **"Add connector"** dari menu. 2. Dalam dialog, pilih **"Add custom connector"**. 3. **Name:** `astroway-hosted` 4. **URL:** `https://mcp.astroway.info/mcp` 5. Buka **"Advanced settings"** → di **"Custom headers"** tambahkan: - **Key:** `Authorization` - **Value:** `Bearer aw_live_...` (kunci API-mu) 6. **Add** → temukan `astroway-hosted` dalam daftar Connectors, aktifkan sakelar. Tidak perlu me-restart Claude Desktop. Klik `+` di obrolan baru — di Connectors akan muncul `astroway-hosted` dengan semua 630 alat + 12 prompt + 14 sumber daya. Untuk Cline / Continue / Windsurf atau versi lama Claude Desktop / Cursor: ```json { "mcpServers": { "astroway-hosted": { "url": "https://mcp.astroway.info/mcp", "headers": { "Authorization": "Bearer aw_live_..." } } } } ``` Jalur ke file konfigurasi: - **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json` - **Cursor:** `~/.cursor/mcp.json` (global) atau `.cursor/mcp.json` (di workspace) - **Cline (VS Code):** `.cline/mcp.json` di workspace - **Continue:** `~/.continue/config.json` (blok `mcpServers`) - **Windsurf:** `~/.codeium/windsurf/mcp_config.json` Setelah mengedit, restart klien sepenuhnya (Cmd+Q → buka lagi). ### Verifikasi ```bash curl https://mcp.astroway.info/health # {"status":"ok","version":"…","uptime_sec":…,"mcp_protocol_version":"2024-11-05"} ``` Di klien — minta: *"List 5 AstroWay tool names from astroway-hosted"*. Seharusnya mengembalikan nama seperti `astroway_western_chart`, `astroway_horoscope_daily`, `astroway_vedic_panchang_full`, … ### Batasan rate Endpoint hosted dilindungi oleh pembatasan berlapis: Cloudflare DDoS layer + nginx `120 req/min/IP` + bucket in-memory `60/60s/(IP+key)`. Klien MCP nyata (Claude Desktop, Cursor) tidak mendekati batasan ini — mereka tidak melakukan permintaan burst. Jika otomatisasi/CI-mu memerlukan > 120 req/min — gunakan mode **stdio** (tidak ada batasan di sana, berjalan langsung melalui `api.astroway.info/v1/*` dengan rate-limit tarifmu sendiri). ### Jika `mcp.astroway.info` tidak tersedia sementara Jika endpoint hosted mengembalikan 5xx, klien MCP akan melihat kesalahan saat `tools/list`. Ini **tidak memengaruhi** klien stdio — mereka menjalankan paket npm lokal yang berkomunikasi langsung ke `api.astroway.info/v1/*` tanpa lapisan hosted perantara. **Fallback untuk integrasi kritis:** tambahkan **server MCP kedua** dalam konfigurasi dengan mode stdio — klien akan secara otomatis menggunakan server ini jika hosted tidak merespons `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_..." } } } } ``` Uptime aktual endpoint hosted dapat dilihat di [status.astroway.info](https://status.astroway.info). Insiden > 5 menit dipublikasikan sebagai postmortem dalam 5 hari kerja (sesuai [/sla/](/sla/)). ## Stdio (npm) — untuk pengembangan lokal [`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp) — paket npm yang berjalan secara lokal sebagai subprocess. Satu paket npm, integrasi asli dengan Claude Desktop, Cursor, dan klien MCP kompatibel mana pun. ## Cara kerjanya Daftar alat dihasilkan **pada saat build** dari spesifikasi OpenAPI live ([api.astroway.info/v1/openapi.json](https://api.astroway.info/v1/openapi.json)). Setiap rilis paket secara otomatis mengambil semua endpoint baru — tidak perlu dukungan manual. Setiap endpoint menjadi alat dengan struktur: - `tools/list` mengembalikan deskripsi dan skema input (dengan contoh body permintaan) - `tools/call` melakukan HTTP POST ke `https://api.astroway.info/v1/` dengan `ASTROWAY_API_KEY` milikmu - Respons dikembalikan ke agen sebagai JSON terstruktur Setiap rilis juga disertai dengan provenance SLSA ([tersertifikasi Sigstore](https://search.sigstore.dev/)) — ini menjamin bahwa paket npm dibangun dari commit yang sama di repositori publik. ## Instalasi ### Claude Desktop (macOS) Tambahkan ke `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` Restart Claude Desktop. Di bilah bawah obrolan akan muncul indikator 🛠️ dengan jumlah alat yang dimuat. ### Cursor Tambahkan ke `~/.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 Perintah `npx @astroway/mcp` yang sama berfungsi di setiap klien MCP kompatibel. Konfigurasinya identik — hanya jalur file yang berubah: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` | Klien | Jalur ke konfigurasi | |---|---| | **Cline** (VS Code) | `.cline/mcp.json` di root workspace | | **Continue** | `~/.continue/config.json` (di bawah `mcpServers`) | | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | | **GitHub Copilot Chat (VS Code)** | flag pratinjau → `mcp.json` di workspace | | **VS Code MCP extension** | `~/.vscode/mcp.json` | ### Klien MCP lainnya Jalankan sebagai server stdio: ```bash ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp ``` ## Privacy — sejak v1.0.0+ Server MCP ini **tidak mengirimkan apa pun kembali ke AstroWay** selain panggilan API yang kamu perintahkan untuk dieksekusi. Tidak ada telemetri, tidak ada analytics, tidak ada sakelar opt-in/opt-out — diam adalah default. Permintaan keluar membawa dua header identifikasi agar backend AstroWay dapat membedakan lalu lintas MCP dari HTTP langsung dalam log internal: - `User-Agent: astroway-mcp/ (Node/)` - `X-Astroway-Channel: mcp` Keduanya tidak mengandung session ID, fingerprint mesin, atau apa pun yang bersifat personal. Ini adalah semantik standar `User-Agent` — setiap alat CLI mengirim informasi serupa. ## Subset registration — sejak v1.0.0+ Jika hanya menggunakan sebagian katalog — daftarkan subset untuk menjaga jendela konteks LLM tetap ringkas: ```jsonc { "env": { "ASTROWAY_API_KEY": "aw_live_...", "ASTROWAY_TOOL_GROUPS": "western,vedic,relational", // hanya awalan ini "ASTROWAY_READONLY": "1" // lewati ai/horoscope/reports (menggunakan LLM, menghabiskan kredit) } } ``` Grup umum: `western`, `vedic`, `tarot`, `numerology`, `hd` (Human Design), `relational` (synastry/composite/davison), `prognostics` (transits/progressions/returns), `aspects`, `horary`, `geo`, `chinese`, `bazi`, `mayan`, `iching`, `runes`, `geomancy`. Jalankan `npx @astroway/mcp --list-tools` untuk melihat daftar lengkap. `ASTROWAY_READONLY=1` melewati tiga grup yang secara internal memanggil LLM (`ai`, `horoscope`, `reports`) — berguna jika kamu menginginkan perhitungan peta yang deterministik murni tanpa menghabiskan kredit untuk pembuatan teks. ## Komitmen stabilitas — sejak v1.0.0+ - **Katalog dibekukan selama sesi.** 624 tools, 12 prompts, 14 resources tertanam dalam paket npm yang dipublikasikan pada saat build — tidak ada perubahan selama koneksi. Jika klienmu melakukan cache `tools/list` setelah panggilan pertama, ia tetap valid untuk seluruh sesi. - **Identifier alat stabil dalam versi mayor.** Nama di bawah `astroway__` tidak akan diubah atau dihapus dalam `v1.x` tanpa catatan deprecation di `CHANGELOG.md` dan ketersediaan paralel minor. - **Bentuk input alat stabil dalam versi minor.** Pembatasan (regex, range, enum) datang dalam patch; penambahan bidang wajib memerlukan bump minor. - **Pembaruan katalog — dengan penginstalan ulang.** `npm i -g @astroway/mcp@latest` (atau perintah `npx -y @astroway/mcp` dalam konfigurasi) akan mengambil set saat ini pada startup berikutnya. ## Contoh prompt Setelah menghubungkan server, minta AI: ### Peta Natal > Hitung peta natalku — lahir 15 Maret 1990, pukul 14:30, Kyiv. Jelaskan Matahari, Bulan, Ascendant dan temukan aspek ketat. Claude akan memanggil tool `chart` dengan parametermu, menerima JSON terstruktur, dan menjelaskan peta dalam kata-kata. ### Transit > Transit planet lambat apa yang akan terjadi pada peta natalku sepanjang tahun 2027? Claude melakukan dua panggilan tool: pertama `transits` (snapshot saat ini), lalu `transit-calendar` (rentang). Menafsirkan tren. ### Vedic Mahadasha > Jalankan Vimshottari Mahadasha untuk seseorang yang lahir 22.07.1985 pukul 06:45 di Mumbai. Sekarang periode apa orang ini? Melalui tool `vedic/dashas/vimshottari/maha` — timestamp UTC yang tepat dari periode saat ini. ### Synastry > Bandingkan dua peta: A — 10.06.1988 pukul 09:15 London, B — 22.11.1991 pukul 22:40 Berlin. Apa aspek silang terkuat? Tool `synastry` dengan dua blok `chart` + interpretasi skor kompatibilitas. ### Tarot > Tarik 3 kartu Rider-Waite-Smith: Masa Lalu — Sekarang — Masa Depan. Pertanyaan: "haruskah aku menerima pekerjaan baru?". Seed = 42. `tarot/rider-waite/spread` dengan seed tetap untuk reproduktifitas. ## Daftar semua alat Setelah terhubung, tanyakan ke Claude: > Sebutkan semua alat astroway. Atau dari baris perintah: ```bash ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1 # (menjalankan server stdio; panggilan protokol daftar alat dilakukan oleh klien MCP) ``` ## Konfigurasi | Variabel | Default | Deskripsi | Sejak versi | |---|---|---|---| | `ASTROWAY_API_KEY` | *(wajib)* | Live: `aw_live_...`. Sandbox: `aw_test_...`. | 0.1.0 | | `ASTROWAY_BASE_URL` | `https://api.astroway.info/v1` | Override untuk self-hosted/staging. | 0.1.0 | | `ASTROWAY_TOOL_GROUPS` | *(semua grup)* | Awalan grup yang dipisahkan koma untuk membatasi katalog (`western,vedic,relational`). | 1.0.0 | | `ASTROWAY_READONLY` | `0` | `1` melewati grup yang menggunakan LLM (`ai`, `horoscope`, `reports`). | 1.0.0 | | `LOG_LEVEL` | `error` | `silent`/`error`/`warn`/`info`/`debug` — level logging ke stderr. | 0.8.0 | | `LOG_FILE` | *(tidak ditulis)* | Jalur file untuk duplikasi log. | 0.8.0 | | `MCP_FLAT_TOOLS` | `0` | `1` mengembalikan nama flat pra-v0.9 (`chart` alih-alih `astroway_western_chart`). Legacy. | 0.9.0 | ## Mengapa MCP, bukan integrasi langsung LLM umum (tanpa grounding) akan mengatakan *"di suatu tempat pada bulan Juli Saturnus akan membentuk trine ke Jupiter-mu"* — tanpa tanggal yang tepat, dengan deviasi ±15 hari. **Agen MCP** melakukan `tool_use POST /v1/transits` dan mengembalikan timestamp UTC **hingga detik**, menggunakan Swiss Ephemeris asli. Keuntungannya bukan pada LLM, melainkan pada **jaminan bahwa perhitungan itu nyata** — bukan fiksi. ## Distribusi paket - **mcp.so listing:** [mcp.so/server/astroway-mcp/astroway](https://mcp.so/server/astroway-mcp/astroway) - **mcpservers.org:** menunggu persetujuan (per Mei 2026) - **awesome-mcp-servers (punkpeye):** [PR #5972](https://github.com/punkpeye/awesome-mcp-servers/pull/5972) ## Tautan - 📦 npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) - 📘 API docs: [/docs/api/](/docs/api/) - 🔑 Sign up: [/dashboard/sign-up](/dashboard/sign-up) - 💰 Pricing: [/pricing/](/pricing/) - 🌐 Public repo (MIT): [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)