MCP - conectarea Claude / Cursor

Serverul Model Context Protocol AstroWay expune toate cele 771 endpoint-uri ca instrumente pentru un agent AI. Două moduri - ambele sunt suportate nativ de toți clienții compatibili MCP.

Mod	URL / comandă	Când să alegi
Hosted HTTP	https://mcp.astroway.info/mcp	Claude Web (claude.ai în browser), Claude Desktop / Cursor / Code newcomers fără npm, sau când vrei zero-instalare
Stdio (npm)	npx @astroway/mcp	Utilizatori avansați Cursor, dezvoltare locală, conștient de confidențialitate (cheia nu părăsește niciodată mașina ta), offline-ready

Endpoint-ul hosted și pachetul npm utilizează același catalog de instrumente (generat dintr-un singur /v1/openapi.json). Autentificare: aceeași cheie API aw_test_* / aw_live_* - în modul hosted este trimisă prin header-ul Authorization: Bearer …, în stdio - prin variabila de mediu ASTROWAY_API_KEY.

Sursă: github.com/astroway/astroway-mcp · npm: npmjs.com/package/@astroway/mcp · hosted: mcp.astroway.info/health

Hosted (mcp.astroway.info) - zero instalare

Start rapid fără npm - alege-ți clientul. Înainte de instalare, obține o cheie de pe api.astroway.info/dashboard/sign-up (10 000 credite/lună gratuit).

Cursor (un singur clic)

Apasă butonul - Cursor se va deschide, va cere confirmare, va adăuga înregistrarea automat:

Instalează în Cursor →

Pasul 2 obligatoriu - altfel nu va funcționa

Cursor nu poate substitui secretul din deeplink - în ~/.cursor/mcp.json se va înregistra literalul Bearer YOUR_API_KEY, la care serverul răspunde cu 403 invalid_format.

După ce ai apăsat butonul:

1. Cursor Settings (⚙️ colțul dreapta sus) → Tools & MCP → găsește astroway-hosted în listă.
2. Apasă cele trei puncte (⋯) lângă server → Edit configuration.
3. În câmpul Authorization, înlocuiește Bearer YOUR_API_KEY cu Bearer aw_test_… (sau aw_live_…) - cheia ta reală din Dashboard.
4. Salvează → redeschide lista MCP → asigură-te că statusul este enabled + punct verde + contor 780+ tools enabled.

Alternativ - editează fișierul direct: ~/.cursor/mcp.json (headers.Authorization).

Mențiune

Cursor impune o limită de lungime a numelor: server_name:tool_name ≤ 60 de caractere. Aproximativ 90 din cele 780+ instrumente (în mare parte grupurile hellenistic_*, psychological_*, zi_wei_*, zodiac_* și numerology_*) sunt filtrate de Cursor și nu vor fi disponibile prin LLM. Celelalte ~690 funcționează. În Claude Desktop nu există o astfel de limită - catalogul este complet.

Claude Desktop

Settings → Developer → Edit Config deschide claude_desktop_config.json. Acest fișier rulează doar comenzi locale: înregistrarea cu doar url este omisă cu mesajul “Some MCP servers couldn’t be loaded”. Serverul hosted se conectează printr-un bridge mcp-remote, are nevoie de 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_..." }
    }
  }
}

Închide complet Claude Desktop (Cmd+Q) și deschide-l din nou. Cheia se află în env, deoarece Claude Desktop pe Windows rupe argumentul la spațiu după Bearer.

Dialogul Add custom connector din Settings → Connectors acceptă doar numele și URL-ul, nu există câmp pentru header-ul Authorization, deci cheia AstroWay nu poate fi transmisă prin acesta în prezent.

Configurare JSON (manuală)

Pentru Cursor, Cline, Continue și Windsurf, care acceptă url-ul remote direct:

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

Căi către fișierele de configurare:

• Cursor: ~/.cursor/mcp.json (global) sau .cursor/mcp.json (în workspace)
• Cline (VS Code): .cline/mcp.json în workspace
• Continue: ~/.continue/config.json (blocul mcpServers)
• Windsurf: ~/.codeium/windsurf/mcp_config.json

După modificare, repornește complet clientul (Cmd+Q → deschide din nou).

Verificare

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

În client - cere: “List 5 AstroWay tool names from astroway-hosted”. Ar trebui să returneze nume de tipul astroway_western_chart, astroway_horoscope_daily, astroway_vedic_panchang_full, …

Limite de rată

Endpoint-ul hosted este protejat de o limitare pe 3 niveluri: stratul Cloudflare DDoS + proxy edge 120 req/min/IP + bucket in-memory 60/60s/(IP+key). Clienții MCP reali (Claude Desktop, Cursor) nu se apropie de aceste limite - ei nu fac cereri în rafală. Dacă automatizarea / CI-ul tău necesită > 120 req/min - utilizează modul stdio (acolo nu există limite, merge direct prin api.astroway.info/v1/* cu limita de rată a planului tău).

Ce se întâmplă dacă mcp.astroway.info este temporar indisponibil

Dacă endpoint-ul hosted returnează 5xx, clientul MCP va vedea o eroare la tools/list. Acest lucru nu afectează clienții stdio - aceștia rulează un pachet npm local care accesează direct api.astroway.info/v1/* fără stratul hosted intermediar.

Fallback pentru integrări critice: adaugă un al doilea server MCP în configurație cu modul stdio - clientul îl va utiliza automat dacă cel hosted nu răspunde la 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_..." }
    }
  }
}

Uptime-ul real al endpoint-ului hosted este vizibil pe status.astroway.info. Incidente > 5 minute sunt publicate ca postmortem în termen de 5 zile lucrătoare (conform /sla/).

Stdio (npm) - pentru dezvoltare locală

@astroway/mcp - un pachet npm care rulează local ca subprocess. Un singur pachet npm, integrare nativă cu Claude Desktop, Cursor și orice client compatibil MCP.

Cum funcționează

Lista de instrumente este generată la momentul build-ului din specificația OpenAPI live (api.astroway.info/v1/openapi.json). Fiecare lansare a pachetului preia automat toate endpoint-urile noi - nu este nevoie să menții nimic manual.

Fiecare endpoint devine un instrument de tipul:

• tools/list returnează descrierea și schema de intrare (cu un exemplu de corp de cerere)
• tools/call efectuează un HTTP POST către https://api.astroway.info/v1/<path> cu ASTROWAY_API_KEY-ul tău
• Răspunsul este returnat agentului ca JSON structurat

Fiecare lansare este, de asemenea, livrată cu proveniență SLSA (Sigstore-attested) - aceasta este o garanție că pachetul npm este construit exact din commit-ul din depozitul public.

Instalare

Claude Desktop (macOS)

Adaugă în ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Repornește Claude Desktop. În bara de sub chat va apărea un indicator 🛠️ cu numărul de instrumente încărcate.

Cursor

Adaugă în ~/.cursor/mcp.json:

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

Cline / Continue / Windsurf / Copilot / VS Code MCP

Aceeași comandă npx @astroway/mcp funcționează în fiecare client compatibil MCP. Configurația este identică - se schimbă doar calea către fișier:

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

Client	Calea către fișierul de configurare
Cline (VS Code)	.cline/mcp.json la rădăcina workspace-ului
Continue	~/.continue/config.json (sub mcpServers)
Windsurf	~/.codeium/windsurf/mcp_config.json
GitHub Copilot Chat (VS Code)	flag de preview → mcp.json în workspace
VS Code MCP extension	~/.vscode/mcp.json

Alți clienți MCP

Rulează ca server stdio:

ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp

Sfat

Obține cheia - de pe api.astroway.info/dashboard/sign-up. Nivel gratuit - 10 000 credite/lună, fără card.

Confidențialitate - de la v1.0.0+

Acest server MCP nu trimite nimic înapoi către AstroWay în afară de apelurile API pe care tu îi ceri să le execute. Nici o telemetrie, nici un analytics, nici un comutator opt-in/opt-out - tăcere implicită.

Cererile de ieșire poartă două headere de identificare pentru ca backend-ul AstroWay să poată distinge traficul MCP de HTTP direct în propriile log-uri:

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

Niciunul dintre ele nu conține ID de sesiune, amprentă digitală a mașinii sau orice altceva personal. Aceasta este o semantică standard User-Agent - fiecare instrument CLI trimite informații similare.

Înregistrarea subsetului - de la v1.0.0+

Dacă utilizezi doar o parte a catalogului - înregistrează un subset pentru ca fereastra de context a LLM să rămână compactă:

{
  "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)
  }
}

Grupuri comune: western, vedic, tarot, numerology, hd (Human Design), relational (sinastrie/compus/davison), prognostics (tranzite/progresii/reveniri), aspects, horary, geo, chinese, bazi, mayan, iching, runes, geomancy. Rulează npx @astroway/mcp --list-tools pentru a vedea setul complet.

ASTROWAY_READONLY=1 omite trei grupuri care apelează intern LLM (ai, horoscope, reports) - util când vrei o matematică pur deterministă a hărților fără a cheltui credite pe generarea de text.

Angajament de stabilitate - de la v1.0.0+

• Catalogul este înghețat pe durata sesiunii. Peste 780 de instrumente, 12 prompt-uri, 14 resurse sunt încorporate în pachetul npm publicat la momentul build-ului - nimic nu se schimbă în timpul conectării. Dacă clientul tău cachează tools/list după primul apel - acesta rămâne corect pentru întreaga sesiune.
• Identificatorii instrumentelor sunt stabili în cadrul versiunii majore. Numele sub astroway_<group>_<tool> nu va fi redenumit sau șters în cadrul v1.x fără o notă de deprecere în CHANGELOG.md și disponibilitate paralelă pe o versiune minoră.
• Forma de intrare a instrumentului este stabilă în cadrul versiunii minore. Restricțiile (regex, range, enum) vin în patch-uri; adăugarea unui câmp obligatoriu necesită un minor bump.
• Reîmprospătarea catalogului: prin reinstalare. npm i -g @astroway/mcp@latest (sau forma npx -y @astroway/mcp în configurația ta) preia setul curent la următoarea pornire.

Exemple de prompt-uri

După conectarea serverului, cere AI-ului:

Hartă natală

Calculează-mi harta natală - născut pe 15 martie 1990, 14:30, Kiev. Descrie Soarele, Luna, Ascendentul și găsește aspectele strânse.

Claude va apela instrumentul chart cu parametrii tăi, va primi un JSON structurat și va descrie harta în cuvinte.

Tranzite

Ce tranzite semnificative ale planetelor lente vor afecta harta mea natală pe parcursul anului 2027?

Claude face două apeluri de instrumente: mai întâi transits (instantaneu curent), apoi transit-calendar (interval). Interpretează tendințele.

Mahadasha Vedică

Rulează Vimshottari Mahadasha pentru o persoană născută pe 22.07.1985 la 06:45 în Mumbai. În ce perioadă se află această persoană acum?

Prin instrumentul vedic/dashas/vimshottari/maha - timestamp-ul UTC exact al perioadei curente.

Sinastrie

Compară două hărți: A - 10.06.1988 09:15 Londra, B - 22.11.1991 22:40 Berlin. Care sunt cele mai puternice aspecte încrucișate?

Instrumentul synastry cu două blocuri chart + interpretarea scorului de compatibilitate.

Tarot

Extrage 3 cărți Rider-Waite-Smith: Trecut - Prezent - Viitor. Întrebare: “ar trebui să accept noul loc de muncă?”. Seed = 42.

tarot/rider-waite/spread cu un seed fix pentru reproductibilitate.

Lista tuturor instrumentelor

După conectare, întreabă-l pe Claude:

Listează toate instrumentele astroway.

Sau din linia de comandă:

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)

Configurație

Variabilă	Implicit	Descriere	De la versiunea
ASTROWAY_API_KEY	(obligatoriu)	Live: aw_live_.... Sandbox: aw_test_....	0.1.0
ASTROWAY_BASE_URL	https://api.astroway.info/v1	Override pentru medii self-hosted/staging.	0.1.0
ASTROWAY_TOOL_GROUPS	(toate grupurile)	Prefixe separate prin virgulă pentru a limita catalogul (western,vedic,relational).	1.0.0
ASTROWAY_READONLY	0	1 omite grupurile susținute de LLM (ai, horoscope, reports).	1.0.0
LOG_LEVEL	error	silent/error/warn/info/debug - nivelul de logare pe stderr.	0.8.0
LOG_FILE	(nu se scrie)	Calea către fișierul pentru duplicarea log-urilor.	0.8.0
MCP_FLAT_TOOLS	0	1 returnează nume plate pre-v0.9 (chart în loc de astroway_western_chart). Moștenit.	0.9.0

De ce MCP, nu integrare directă

Un LLM generic (fără grounding) va spune “undeva în iulie Saturn va forma un trigon cu Jupiterul tău” - fără o dată exactă, cu o abatere de ±15 zile. Un agent MCP efectuează tool_use POST /v1/transits și returnează un timestamp UTC până la secundă, pe un Swiss Ephemeris real.

Avantajul nu este în LLM, ci în garanția că matematica este reală - nu inventată.

Distribuția pachetului

• Listare mcp.so: mcp.so/server/astroway-mcp/astroway
• mcpservers.org: așteaptă aprobarea (la data de mai 2026)
• awesome-mcp-servers (punkpeye): PR #5972

Link-uri

• 📦 npm: npmjs.com/package/@astroway/mcp
• 📘 Documentație API: /docs/api/
• 🔑 Înregistrare: /dashboard/sign-up
• 💰 Prețuri: /pricing/
• 🌐 Repo public (MIT): github.com/astroway/astroway-mcp