# MCP — připojení Claude / Cursor
Model Context Protocol server AstroWay vystavuje **všechny {siteMeta.endpoints} endpointy** jako nástroje pro AI agenty. Podporovány jsou dva režimy — oba jsou nativně podporovány všemi klienty kompatibilními s MCP.
| Režim | URL / příkaz | Kdy zvolit |
|---|---|---|
| **Hosted HTTP** | `https://mcp.astroway.info/mcp` | Claude Web (claude.ai v prohlížeči), Claude Desktop / Cursor / Code pro začátečníky bez npm, nebo když chceš zero-install |
| **Stdio (npm)** | `npx @astroway/mcp` | Power uživatelé Cursoru, lokální vývoj, privacy-conscious (klíč nikdy neopustí tvůj stroj), připraveno pro offline |
Hostovaný endpoint i npm balíček používají **stejný katalog nástrojů** (generováno z jednoho `/v1/openapi.json`). Autentizace: stejný `aw_test_*` / `aw_live_*` API klíč — u hostovaného se posílá přes `Authorization: Bearer …` header, u stdio přes proměnnou prostředí `ASTROWAY_API_KEY`.
Zdroj: [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`) — zero install
Rychlý start bez npm — vyber si svého klienta. Před instalací si vezmi klíč na [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up) (10 000 kreditů/měsíc zdarma).
Klikni na tlačítko — otevře se Cursor, požádá o potvrzení a automaticky přidá záznam:
Nainstalovat v Cursoru →
:::caution[Povinný 2. krok — jinak to nebude fungovat]
Cursor neumí dosadit tajný klíč z deeplinku — v `~/.cursor/mcp.json` se zapíše doslovný text `Bearer YOUR_API_KEY`, na který server odpoví `403 invalid_format`.
**Po kliknutí na tlačítko:**
1. **Cursor Settings** (⚙️ v pravém horním rohu) → **Tools & MCP** → najdi `astroway-hosted` v seznamu.
2. Klikni na tři tečky (`⋯`) vedle serveru → **Edit configuration**.
3. V poli `Authorization` nahraď `Bearer YOUR_API_KEY` svým skutečným klíčem z [Dashboardu](https://api.astroway.info/dashboard/keys) ve formátu `Bearer aw_test_…` (nebo `aw_live_…`).
4. Ulož → znovu otevři seznam MCP → ujisti se, že je status **enabled** + zelená tečka + počítadlo `630 tools enabled`.
Alternativně můžeš soubor upravit přímo: `~/.cursor/mcp.json` (`headers.Authorization`).
:::
Bez úpravy JSON. V libovolném chatu Clauda Desktop:
1. Klikni na **`+`** vlevo od vstupního pole → v menu vyber **"Add connector"**.
2. V dialogu vyber **"Add custom connector"**.
3. **Name:** `astroway-hosted`
4. **URL:** `https://mcp.astroway.info/mcp`
5. Rozbal **"Advanced settings"** → v **"Custom headers"** přidej:
- **Key:** `Authorization`
- **Value:** `Bearer aw_live_...` (tvůj klíč)
6. **Add** → najdi `astroway-hosted` v seznamu Connectors, zapni přepínač.
Clauda Desktop **není třeba restartovat**. Klikni na `+` v novém chatu — v Connectors se objeví `astroway-hosted` se všemi 630 nástroji + 12 promptů + 14 zdrojů.
Pro Cline / Continue / Windsurf nebo starší verze Clauda Desktop / Cursor:
```json
{
"mcpServers": {
"astroway-hosted": {
"url": "https://mcp.astroway.info/mcp",
"headers": {
"Authorization": "Bearer aw_live_..."
}
}
}
}
```
Cesty k konfigům:
- **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álně) nebo `.cursor/mcp.json` (v workspace)
- **Cline (VS Code):** `.cline/mcp.json` v workspace
- **Continue:** `~/.continue/config.json` (blok `mcpServers`)
- **Windsurf:** `~/.codeium/windsurf/mcp_config.json`
Po úpravách restartuj klienta úplně (Cmd+Q → otevřít znovu).
### Kontrola
```bash
curl https://mcp.astroway.info/health
# {"status":"ok","version":"…","uptime_sec":…,"mcp_protocol_version":"2024-11-05"}
```
V klientovi požádej: *"Vypiš 5 názvů nástrojů AstroWay z astroway-hosted"*. Mělo by vrátit názvy jako `astroway_western_chart`, `astroway_horoscope_daily`, `astroway_vedic_panchang_full`, …
### Rate limits
Hostovaný endpoint je chráněn 3-vrstvým omezením: Cloudflare DDoS vrstva + nginx `120 req/min/IP` + in-memory bucket `60/60s/(IP+key)`. Reální MCP klienti (Claude Desktop, Cursor) se těchto limitů nepřibližují — nedělají burstové dotazy. Pokud tvá automatizace / CI potřebuje > 120 req/min — použij **stdio** režim (tam nejsou žádná omezení, komunikuje přímo s `api.astroway.info/v1/*` podle tvého tarifního rate-limitu).
### Co když je `mcp.astroway.info` dočasně nedostupný
Pokud hostovaný endpoint vrátí 5xx, MCP klient uvidí chybu při `tools/list`. To **neovlivňuje** stdio klienty — ti spouští lokální npm balíček, který komunikuje přímo s `api.astroway.info/v1/*` bez prostřednického hostovaného serveru.
**Fallback pro kritické integrace:** přidej **druhý MCP server** do konfigurace ve stdio režimu — klient ho automaticky použije, pokud hostovaný nereaguje na `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_..." }
}
}
}
```
Skutečný uptime hostovaného endpointu je vidět na [status.astroway.info](https://status.astroway.info). Incidenty delší než 5 minut zveřejňujeme jako postmortem do 5 pracovních dnů (dle [/sla/](/sla/)).
## Stdio (npm) — pro lokální vývoj
[`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp) je npm balíček, který se spouští lokálně jako subprocess. Jeden balíček, nativní integrace s Claudem Desktop, Cursoem a jakýmkoli klientem kompatibilním s MCP.
## Jak to funguje
Seznam nástrojů se generuje **v době buildu** z live OpenAPI specifikace ([api.astroway.info/v1/openapi.json](https://api.astroway.info/v1/openapi.json)). Každé vydání balíčku automaticky zahrnuje všechny nové endpointy — není třeba nic ručně udržovat.
Každý endpoint se stává nástrojem ve tvaru:
- `tools/list` vrací popis a schéma vstupu (s příkladem těla požadavku)
- `tools/call` provádí HTTP POST na `https://api.astroway.info/v1/` s tvým `ASTROWAY_API_KEY`
- Odpověď se vrací agentovi jako strukturovaný JSON
Každé vydání je navíc opatřeno SLSA proveniencí ([Sigstore-podepsáno](https://search.sigstore.dev/)) — to zaručuje, že byl npm balíček sestaven právě z commitu v veřejném repozitáři.
## Instalace
### Claude Desktop (macOS)
Přidej do `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"astroway": {
"command": "npx",
"args": ["-y", "@astroway/mcp"],
"env": {
"ASTROWAY_API_KEY": "aw_live_..."
}
}
}
}
```
Restartuj Clauda Desktop. V liště pod chatem se objeví ikona 🛠️ s počtem načtených nástrojů.
### Cursor
Přidej do `~/.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
Stejný příkaz `npx @astroway/mcp` funguje u každého klienta kompatibilního s MCP. Konfigurace je identická — liší se pouze cesta k souboru:
```json
{
"mcpServers": {
"astroway": {
"command": "npx",
"args": ["-y", "@astroway/mcp"],
"env": { "ASTROWAY_API_KEY": "aw_live_..." }
}
}
}
```
| Klient | Cesta ke konfigu |
|---|---|
| **Cline** (VS Code) | `.cline/mcp.json` v kořeni workspace |
| **Continue** | `~/.continue/config.json` (pod `mcpServers`) |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
| **GitHub Copilot Chat (VS Code)** | preview-flagu → `mcp.json` v workspace |
| **VS Code MCP extension** | `~/.vscode/mcp.json` |
### Ostatní MCP klienti
Spusť jako stdio server:
```bash
ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp
```
## Privacy — od verze v1.0.0+
Tento MCP server **neposílá nic zpět do AstroWay** kromě těch API volání, která mu zadáš k provedení. Žádná telemetrie, žádný analytics, žádný přepínač opt-in/opt-out — mlčení je výchozí nastavení.
Výstupní požadavky obsahují dva identifikační hlavičky, aby mohl AstroWay backend rozlišovat MCP provoz od přímého HTTP ve vlastních logech:
- `User-Agent: astroway-mcp/ (Node/)`
- `X-Astroway-Channel: mcp`
Žádná z těchto hlaviček neobsahuje session ID, fingerprint stroje ani nic osobního. Jedná se o standardní sémantiku `User-Agent` — každý CLI nástroj posílá podobné informace.
## Subset registration — od verze v1.0.0+
Pokud používáš pouze část katalogu — zaregistruj si podskupinu, aby zůstalo kontextové okno LLM kompaktní:
```jsonc
{
"env": {
"ASTROWAY_API_KEY": "aw_live_...",
"ASTROWAY_TOOL_GROUPS": "western,vedic,relational", // pouze tyto prefixy
"ASTROWAY_READONLY": "1" // přeskočí ai/horoscope/reports (LLM-backed, spotřebovávají kredity)
}
}
```
Běžné skupiny: `western`, `vedic`, `tarot`, `numerology`, `hd` (Human Design), `relational` (synastrie/kompozit/Davison), `prognostics` (transity/progresie/returns), `aspects`, `horary`, `geo`, `chinese`, `bazi`, `mayan`, `iching`, `runes`, `geomancy`. Spusť `npx @astroway/mcp --list-tools`, abys viděl celý seznam.
`ASTROWAY_READONLY=1` přeskočí tři skupiny, které interně využívají LLM (`ai`, `horoscope`, `reports`) — užitečné, když chceš čistou deterministickou astrologickou matematiku bez nákladů na generování textu.
## Stability commitment — od verze v1.0.0+
- **Seznam nástrojů je zmrazen po dobu relace.** 624 nástrojů, 12 promptů, 14 zdrojů jsou součástí vydaného npm balíčku v době buildu — během připojení se nic nemění. Pokud tvůj klient cacheuje `tools/list` po prvním volání, zůstává pro celou relaci správný.
- **Identifikátory nástrojů jsou stabilní v rámci major verze.** Název pod `astroway__` nebude přejmenován ani odstraněn uvnitř `v1.x` bez oznámení v `CHANGELOG.md` a současné dostupnosti v nižší minor verzi.
- **Tvar vstupu nástroje je stabilní v rámci minor verze.** Zúžení (regex, rozsah, enum) přichází v patchech; přidání povinného pole vyžaduje minor bump.
- **Obnovení katalogu — reinstalací.** `npm i -g @astroway/mcp@latest` (nebo `npx -y @astroway/mcp` ve tvém konfigu) načte aktuální sadu při dalším startu.
## Ukázkové prompty
Po připojení serveru požádej AI:
### Natalní mapa
> Spočti mou natalní mapu — narozený 15. března 1990, 14:30, Kyjev. Popiš Slunce, Měsíc, Ascendent a najdi těsné aspekty.
Claude zavolá nástroj `chart` s tvými parametry, získá strukturovaný JSON a popíše mapu slovy.
### Transity
> Jaké významné transity pomalých planet nastanou v mé natalní mapě během roku 2027?
Claude provede dva volání nástrojů: nejprve `transits` (aktuální snímek), poté `transit-calendar` (rozsah). Interpretuje trendy.
### Vedic Mahadasha
> Spusť Vimshottari Mahadasha pro osobu narozenou 22.07.1985 06:45 v Mumbaji. V jakém období se tato osoba právě nachází?
Pomocí nástroje `vedic/dashas/vimshottari/maha` — přesný UTC timestamp aktuálního období.
### Synastrie
> Porovnej dvě mapy: A — 10.06.1988 09:15 Londýn, B — 22.11.1991 22:40 Berlín. Jaké jsou nejsilnější cross-aspekty?
Nástroj `synastry` se dvěma bloky `chart` + interpretace skóre kompatibility.
### Tarot
> Vytáhni 3 karty Rider-Waite-Smith: Minulost — Přítomnost — Budoucnost. Otázka: „Mám přijmout novou práci?“. Seed = 42.
Nástroj `tarot/rider-waite/spread` s pevným seedem pro reprodukovatelnost.
## Seznam všech nástrojů
Po připojení požádej Clauda:
> Vypiš všechny astroway nástroje.
Nebo z příkazové řádky:
```bash
ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1
# (spustí stdio server; protokolární volání tools/list provádí MCP klient)
```
## Konfigurace
| Proměnná | Výchozí hodnota | Popis | Od verze |
|---|---|---|---|
| `ASTROWAY_API_KEY` | *(povinné)* | Live: `aw_live_...`. Sandbox: `aw_test_...`. | 0.1.0 |
| `ASTROWAY_BASE_URL` | `https://api.astroway.info/v1` | Předefinování pro self-hosted/staging prostředí. | 0.1.0 |
| `ASTROWAY_TOOL_GROUPS` | *(všechny skupiny)* | Seznam prefixů oddělených čárkou pro omezení katalogu (`western,vedic,relational`). | 1.0.0 |
| `ASTROWAY_READONLY` | `0` | `1` přeskočí LLM-backed skupiny (`ai`, `horoscope`, `reports`). | 1.0.0 |
| `LOG_LEVEL` | `error` | `silent`/`error`/`warn`/`info`/`debug` — úroveň logování na stderr. | 0.8.0 |
| `LOG_FILE` | *(nepíše se)* | Cesta k souboru pro duplikaci logů. | 0.8.0 |
| `MCP_FLAT_TOOLS` | `0` | `1` vrací stará plochá jména z před verze 0.9 (`chart` místo `astroway_western_chart`). Legacy. | 0.9.0 |
## Proč MCP a ne přímá integrace
Obecný LLM (bez grounding) řekne *„někdy v červenci Saturn vytvoří trigon k tvému Jupiteru“* — bez přesného data, s driftem ±15 dní. **MCP agent** provede `tool_use POST /v1/transits` a vrátí UTC timestamp **na sekundu přesně**, založený na skutečném Swiss Ephemeris.
Výhoda není v LLM, ale v **zaručení, že matematika je skutečná** — ne vymyšlená.
## Distribuce balíčku
- **mcp.so listing:** [mcp.so/server/astroway-mcp/astroway](https://mcp.so/server/astroway-mcp/astroway)
- **mcpservers.org:** čeká na schválení (květen 2026)
- **awesome-mcp-servers (punkpeye):** [PR #5972](https://github.com/punkpeye/awesome-mcp-servers/pull/5972)
## Odkazy
- 📦 npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp)
- 📘 API dokumentace: [/docs/api/](/docs/api/)
- 🔑 Registrace: [/dashboard/sign-up](/dashboard/sign-up)
- 💰 Ceník: [/pricing/](/pricing/)
- 🌐 Veřejné repo (MIT): [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)