# MCP – kapcsolódás Claude / Cursor
Az AstroWay **MCP-szerver** az összes {siteMeta.endpoints} endpointot **eszközökként** teszi elérhetővé AI-ügynökök számára. Két üzemmód támogatott — mindkettőt natív módon támogatják az összes MCP-kompatibilis kliens.
| Üzemmód | URL / parancs | Mikor válaszd? |
|---|---|---|
| **Hosted HTTP** | `https://mcp.astroway.info/mcp` | A Claude Web (claude.ai böngészőben), Claude Desktop / Cursor / Code kezdők npm nélkül, vagy ha nullás telepítést szeretnél |
| **Stdio (npm)** | `npx @astroway/mcp` | Cursor power userek, helyi fejlesztés, privacy-tudatosak (a kulcs soha nem hagyja el a géped), offline-ready |
A hosted endpoint és az npm-csomag **ugyanazt a katalógust** használja (egyetlen `/v1/openapi.json` generálja). Auth: ugyanaz az `aw_test_*` / `aw_live_*` API-kulcs — a hosted esetében `Authorization: Bearer …` headerrel küldöd, stdio esetében pedig `ASTROWAY_API_KEY` környezeti változóként.
Forrás: [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`) — nullás telepítés
Gyors indítás npm nélkül — válaszd ki a kliensedet. A telepítés előtt szerezd be a kulcsot a [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up) oldalon (10 000 ingyenes hitel/hónap).
Kattints a gombra — a Cursor megnyílik, megerősítést kér, majd automatikusan hozzáadja a bejegyzést:
Telepítés a Cursorben →
:::caution[Kötelező 2. lépés — különben nem fog működni]
A Cursor nem tudja behelyettesíteni a titkos kulcsot a deeplinkből — a `~/.cursor/mcp.json` fájlba a `Bearer YOUR_API_KEY` literál kerül, amire a szerver `403 invalid_format` válasszal reagál.
**A gombra kattintás után:**
1. **Cursor Beállítások** (⚙️ jobb felső sarok) → **Eszközök & MCP** → keresd meg a `astroway-hosted` listát.
2. Kattints a három pontra (`⋯`) a szerver mellett → **Konfiguráció szerkesztése**.
3. A `Authorization` mezőben cseréld ki a `Bearer YOUR_API_KEY` szöveget `Bearer aw_test_…` (vagy `aw_live_…`) formátumra — a saját kulcsodra a [Dashboard](https://api.astroway.info/dashboard/keys) oldalon.
4. Mentsd el → nyisd újra az MCP-listát, és ellenőrizd, hogy a státusz **engedélyezve** + zöld pont + `630 eszköz engedélyezve` számláló látható.
Alternatív megoldásként szerkeszd közvetlenül a fájlt: `~/.cursor/mcp.json` (`headers.Authorization`).
:::
JSON-szerkesztés nélkül. Bármelyik Claude Desktop csevegésben:
1. Kattints a **`+`** gombra a beviteli mező mellett → a menüből válaszd a **"Add connector"** lehetőséget.
2. A párbeszédablakban válaszd a **"Add custom connector"** opciót.
3. **Név:** `astroway-hosted`
4. **URL:** `https://mcp.astroway.info/mcp`
5. Nyisd ki a **"Advanced settings"** részt → a **"Custom headers"** részben add hozzá:
- **Key:** `Authorization`
- **Value:** `Bearer aw_live_...` (a saját kulcsod)
6. **Add** → keresd meg a `astroway-hosted` listát a Connectors között, és kapcsolja be a kapcsolót.
Nem kell újraindítani a Claude Desktopot. Kattints a `+` gombra egy új csevegésben — a Connectors listában megjelenik a `astroway-hosted` az összes 630 eszközzel + 12 prompttal + 14 erőforrással.
A Cline / Continue / Windsurf vagy a régi Claude Desktop / Cursor verziókhoz:
```json
{
"mcpServers": {
"astroway-hosted": {
"url": "https://mcp.astroway.info/mcp",
"headers": {
"Authorization": "Bearer aw_live_..."
}
}
}
}
```
Konfigurációs fájlok elérési útjai:
- **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json`
- **Cursor:** `~/.cursor/mcp.json` (globálisan) vagy `.cursor/mcp.json` (a workspace-ben)
- **Cline (VS Code):** `.cline/mcp.json` a workspace-ben
- **Continue:** `~/.continue/config.json` (a `mcpServers` blokk)
- **Windsurf:** `~/.codeium/windsurf/mcp_config.json`
A szerkesztés után teljesen indítsd újra a klienst (Cmd+Q → újra megnyitás).
### Ellenőrzés
```bash
curl https://mcp.astroway.info/health
# {"status":"ok","version":"…","uptime_sec":…,"mcp_protocol_version":"2024-11-05"}
```
A kliensben kérdezd meg: *"List 5 AstroWay tool names from astroway-hosted"*. Vissza kell kapnod olyan neveket, mint `astroway_western_chart`, `astroway_horoscope_daily`, `astroway_vedic_panchang_full`, …
### Rate limits
A hosted endpoint háromszintű korlátozással védett: Cloudflare DDoS-védelem + nginx `120 req/min/IP` + in-memory bucket `60/60s/(IP+key)`. A valós MCP-kliensek (Claude Desktop, Cursor) nem közelítik meg ezeket a határokat — nem küldenek burst-kéréseket. Ha a saját automatizálásod / CI-d > 120 req/min-et igényel, használd a **stdio** üzemmódot (itt nincsenek korlátok, közvetlenül az `api.astroway.info/v1/*` endpointot hívja a saját tarifád rate-limitjével).
### Mi történik, ha a `mcp.astroway.info` ideiglenesen nem elérhető?
Ha a hosted endpoint 5xx hibát ad vissza a `tools/list` híváskor, az MCP-kliens hibát fog látni. Ez **nincs hatással** a stdio-kliensekre — azok a helyi npm-csomagot futtatják, amely közvetlenül az `api.astroway.info/v1/*` endpointot hívja a hosted réteg kihagyásával.
**Kritikus integrációk esetében fallback:** adj hozzá egy **második MCP-szervert** a konfigurációhoz stdio-üzemmóddal — a kliens automatikusan átkapcsol, ha a hosted nem válaszol a `tools/list` hívásra:
```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_..." }
}
}
}
```
A hosted endpoint tényleges uptime-ja a [status.astroway.info](https://status.astroway.info) oldalon látható. Az incidensek > 5 percet 5 munkanapon belül posztmortemként közöljük (lásd [/sla/](/sla/)).
## Stdio (npm) — helyi fejlesztéshez
A [`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp) npm-csomag helyi subprocessként fut. Egyetlen npm-csomag, natív integráció a Claude Desktoptal, Cursorral és bármely MCP-kompatibilis klienssel.
## Hogyan működik?
A katalógus **build időpontjában** generálódik a live OpenAPI-spec-ből ([api.astroway.info/v1/openapi.json](https://api.astroway.info/v1/openapi.json)). Minden csomagkiadás automatikusan felveszi az összes új endpointot — semmit sem kell manuálisan karbantartani.
Minden endpoint eszközzé alakul:
- A `tools/list` leírja a bemenet és a kimenet sémáját (a kérési testtel együtt)
- A `tools/call` HTTP POST-kérést küld a `https://api.astroway.info/v1/` endpointra a saját `ASTROWAY_API_KEY`eddel
- A választ strukturált JSON-ként küldi vissza az ügynöknek
Minden kiadás SLSA származásellenőrzéssel is rendelkezik ([Sigstore-tanúsítvány](https://search.sigstore.dev/)) — ez garantálja, hogy az npm-csomag pontosan a nyilvános repó adott commitjából készült.
## Telepítés
### Claude Desktop (macOS)
Add hozzá a `~/Library/Application Support/Claude/claude_desktop_config.json` fájlhoz:
```json
{
"mcpServers": {
"astroway": {
"command": "npx",
"args": ["-y", "@astroway/mcp"],
"env": {
"ASTROWAY_API_KEY": "aw_live_..."
}
}
}
}
```
Indítsd újra a Claude Desktopot. A csevegés alatt megjelenik a 🛠️ ikon a betöltött eszközök számával.
### Cursor
Add hozzá a `~/.cursor/mcp.json` fájlhoz:
```json
{
"mcpServers": {
"astroway": {
"command": "npx",
"args": ["-y", "@astroway/mcp"],
"env": { "ASTROWAY_API_KEY": "aw_live_..." }
}
}
}
```
### Cline / Continue / Windsurf / Copilot / VS Code MCP
Ugyanaz az `npx @astroway/mcp` parancs működik minden MCP-kompatibilis kliensben. A konfiguráció azonos — csak a fájl elérési útja változik:
```json
{
"mcpServers": {
"astroway": {
"command": "npx",
"args": ["-y", "@astroway/mcp"],
"env": { "ASTROWAY_API_KEY": "aw_live_..." }
}
}
}
```
| Kliens | Konfigurációs fájl elérési útja |
|---|---|
| **Cline** (VS Code) | `.cline/mcp.json` a workspace gyökerében |
| **Continue** | `~/.continue/config.json` (a `mcpServers` alatt) |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
| **GitHub Copilot Chat (VS Code)** | preview-flagnál → `mcp.json` a workspace-ben |
| **VS Code MCP kiterjesztés** | `~/.vscode/mcp.json` |
### Egyéb MCP-kliensek
Futtasd stdio-szerverként:
```bash
ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp
```
## Privacy — v1.0.0+ óta
Ez az MCP-szerver **semmit sem küld vissza az AstroWay-hoz**, csak azokat az API-hívásokat, amelyeket te végrehajtani kérsz tőle. Semmilyen telemetria, analytics vagy opt-in/opt-out kapcsoló — csend az alapértelmezett.
A kimenő kérések két azonosító fejlécet hordoznak, hogy az AstroWay backend meg tudja különböztetni az MCP-forgalmat a közvetlen HTTP-forgalomtól a saját naplóiban:
- `User-Agent: astroway-mcp/ (Node/)`
- `X-Astroway-Channel: mcp`
Egyik sem tartalmaz session ID-t, géptulajdonságot vagy bármilyen személyes adatot. Ez a standard `User-Agent` szemanatika — minden CLI-eszköz ilyen információkat küld.
## Részhalmaz regisztráció — v1.0.0+ óta
Ha csak a katalógus egy részét használod, regisztrálj egy részhalmazt, hogy az LLM kontextusablaka kompakt maradjon:
```jsonc
{
"env": {
"ASTROWAY_API_KEY": "aw_live_...",
"ASTROWAY_TOOL_GROUPS": "western,vedic,relational", // csak ezek a prefixek
"ASTROWAY_READONLY": "1" // kihagyja az ai/horoscope/reports csoportokat (LLM-alapúak, hitelt emésztenek)
}
}
```
Gyakori csoportok: `western`, `vedic`, `tarot`, `numerology`, `hd` (Human Design), `relational` (szinasztria/kompozit/Davison), `prognostics` (tranzitok/progressziók/visszatérések), `aspects`, `horary`, `geo`, `chinese`, `bazi`, `mayan`, `iching`, `runes`, `geomancy`. Futtasd a `npx @astroway/mcp --list-tools` parancsot a teljes lista megtekintéséhez.
Az `ASTROWAY_READONLY=1` kihagyja a három csoportot, amelyek belsőleg LLM-et hívnak (`ai`, `horoscope`, `reports`) — hasznos, ha tisztán determinisztikus asztrológiai számításokat szeretnél anélkül, hogy hitelt pazarolnál szöveggenerálásra.
## Stabilitási kötelezettség — v1.0.0+ óta
- **A katalógus lefagyasztva a munkamenet alatt.** 624 eszköz, 12 prompt és 14 erőforrás be van építve a közzétett npm-csomagba a build pillanatában — semmi sem változik a csatlakozás alatt. Ha a kliensed a `tools/list` hívás után cache-el, az érvényes marad a teljes munkamenetre.
- **Az eszközazonosítók stabilak a major verziószámokon belül.** A `astroway__` név nem lesz átnevezve vagy törölve a `v1.x` verziókban deprecation note nélkül a `CHANGELOG.md`-ben és egyidejű minor verzió párhuzamos elérhetősége mellett.
- **Az eszköz bemenet alakja stabil a minor verziószámokon belül.** A megszorítások (regex, range, enum) a patch verziókban érkeznek; kötelező mező hozzáadása minor verzióbummot igényel.
- **A katalógus frissítése újratelepítéssel történik.** `npm i -g @astroway/mcp@latest` (vagy a `npx -y @astroway/mcp` forma a saját konfigurációdban) a következő indításkor frissíti a katalógust.
## Promptpéldák
A szerver csatlakoztatása után kérdezd meg az AI-t:
### Natív kártya
> Számítsd ki a natív kártyámat — 1990. március 15., 14:30, Kijev. Írd le a Napot, Holdat, Ascendenset, és keresd meg a szoros aspektusokat.
A Claude meghívja a `chart` eszközt a paramétereiddel, JSON-t kap, majd leírja a kártyát szavakkal.
### Tranzitok
> Mely jelentős tranzitok esnek a natív kártyámra 2027-ben?
A Claude két eszközhívást végez: először a `transits` (aktuális pillanatkép), majd a `transit-calendar` (időtartomány). Az trendeket értelmezi.
### Vedic Mahadasha
> Indítsd el a Vimshottari Mahadasha-t egy olyan személy számára, aki 1985. július 22-án 06:45-kor született Mumbaiban. Ebben a periódusban hol tart most ez a személy?
A `vedic/dashas/vimshottari/maha` eszközön keresztül — pontos UTC-timestamp a jelenlegi periódusnak.
### Szinasztria
> Hasonlítsd össze a két kártyát: A — 1988. június 10. 09:15 London, B — 1991. november 22. 22:40 Berlin. Melyek a legerősebb kereszt-aspektusok?
A `synastry` eszköz két `chart` blokkal + a kompatibilitási pontszám értelmezése.
### Tarot
> Húzz három Rider-Waite-Smith kártyát: Múlt — Jelen — Jövő. Kérdés: „Érdemes-e elfogadni az új állást?”. Seed = 42.
A `tarot/rider-waite/spread` eszköz fix seeddel a reprodukálhatóságért.
## Az összes eszköz listája
A csatlakoztatás után kérdezd meg a Claudent:
> Sorold fel az összes astroway-eszközt.
Vagy parancssorból:
```bash
ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1
# (indítja a stdio-szervert; a protokoll szerinti eszközlista-hívások az MCP-kliensből érkeznek)
```
## Konfiguráció
| Változó | Alapértelmezett | Leírás | Verzió óta |
|---|---|---|---|
| `ASTROWAY_API_KEY` | *(kötelező)* | Live: `aw_live_...`. Sandbox: `aw_test_...`. | 0.1.0 |
| `ASTROWAY_BASE_URL` | `https://api.astroway.info/v1` | Override self-hosted/staging környezetekhez. | 0.1.0 |
| `ASTROWAY_TOOL_GROUPS` | *(minden csoport)* | Vesszővel elválasztott prefixek a katalógus korlátozásához (`western,vedic,relational`). | 1.0.0 |
| `ASTROWAY_READONLY` | `0` | `1` kihagyja az LLM-alapú csoportokat (`ai`, `horoscope`, `reports`). | 1.0.0 |
| `LOG_LEVEL` | `error` | `silent`/`error`/`warn`/`info`/`debug` — a naplózás szintje a stderr-re. | 0.8.0 |
| `LOG_FILE` | *(nincs írva)* | Elérési út a naplófájlhoz. | 0.8.0 |
| `MCP_FLAT_TOOLS` | `0` | `1` visszaadja a pre-v0.9 síkneveket (`chart` helyett `astroway_western_chart`). Legacy. | 0.9.0 |
## Miért MCP és nem direkt integráció?
A generikus LLM (grounding nélkül) azt mondaná: *„valahol júliusban a Szaturnusz trigont alkot a Jupitereddel”* — pontos dátum nélkül, ±15 napos eltéréssel. Az **MCP-ügynök** pedig `tool_use POST /v1/transits` hívást küld, és **másodperc pontossággal** visszaadja az UTC-timestampot, a valódi Swiss Ephemeris alapján.
Az előny nem az LLM-ben rejlik, hanem abban a **garanciában, hogy a matematika valós** — nem kitalált.
## A csomag terjesztése
- **mcp.so listing:** [mcp.so/server/astroway-mcp/astroway](https://mcp.so/server/astroway-mcp/astroway)
- **mcpservers.org:** approvalra vár (2026 májusi állapot szerint)
- **awesome-mcp-servers (punkpeye):** [PR #5972](https://github.com/punkpeye/awesome-mcp-servers/pull/5972)
## Linkek
- 📦 npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp)
- 📘 API docs: [/docs/api/](/docs/api/)
- 🔑 Regisztráció: [/dashboard/sign-up](/dashboard/sign-up)
- 💰 Árazás: [/pricing/](/pricing/)
- 🌐 Nyílt forráskód (MIT): [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)