# MCP — connexion Claude / Cursor Le serveur Model Context Protocol (MCP) AstroWay expose **tous les {siteMeta.endpoints} endpoints** en tant qu'outils pour les agents IA. Deux modes sont pris en charge nativement par tous les clients compatibles MCP. | Mode | URL / commande | Quand choisir | |---|---|---| | **Hosted HTTP** | `https://mcp.astroway.info/mcp` | Claude Web (claude.ai dans le navigateur), Claude Desktop / Cursor / Code pour les nouveaux venus sans npm, ou si tu veux une installation zéro | | **Stdio (npm)** | `npx @astroway/mcp` | Power users de Cursor, développement local, respect de la vie privée (la clé ne quitte jamais ta machine), prêt pour le mode hors ligne | L'endpoint hébergé et le package npm utilisent **le même catalogue d'outils** (généré à partir du même `/v1/openapi.json`). Authentification : même clé API `aw_test_*` / `aw_live_*` — pour l'hébergé, elle est envoyée via l'en-tête `Authorization: Bearer …`, pour le stdio via la variable d'environnement `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) · hébergé : [mcp.astroway.info/health](https://mcp.astroway.info/health) ## Hosted (`mcp.astroway.info`) — installation zéro Démarrage rapide sans npm — choisis ton client. Avant l'installation, récupère ta clé sur [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up) (10 000 crédits/mois gratuits). Clique sur le bouton — Cursor s'ouvrira, te demandera de confirmer et ajoutera l'entrée automatiquement : Installer dans Cursor → :::caution[Étape 2 obligatoire — sinon ça ne fonctionnera pas] Cursor ne sait pas remplacer le secret dans le deeplink — dans `~/.cursor/mcp.json`, la valeur littérale `Bearer YOUR_API_KEY` sera écrite, ce à quoi le serveur répondra par `403 invalid_format`. **Après avoir cliqué sur le bouton :** 1. **Paramètres de Cursor** (⚙️ coin supérieur droit) → **Outils & MCP** → trouve `astroway-hosted` dans la liste. 2. Clique sur les trois points (`⋯`) à côté du serveur → **Modifier la configuration**. 3. Dans le champ `Authorization`, remplace `Bearer YOUR_API_KEY` par `Bearer aw_test_…` (ou `aw_live_…`) — ta clé réelle depuis le [Tableau de bord](https://api.astroway.info/dashboard/keys). 4. Enregistre → rouvre la liste MCP → vérifie que le statut est **activé** + le point vert + le compteur `630 outils activés`. Sinon, édite directement le fichier : `~/.cursor/mcp.json` (`headers.Authorization`). ::: Sans éditer de JSON. Dans n'importe quel chat de Claude Desktop : 1. Clique sur le **`+`** à gauche du champ de saisie → dans le menu, choisis **"Ajouter un connecteur"**. 2. Dans la boîte de dialogue, choisis **"Ajouter un connecteur personnalisé"**. 3. **Nom :** `astroway-hosted` 4. **URL :** `https://mcp.astroway.info/mcp` 5. Déploie **"Paramètres avancés"** → dans **"En-têtes personnalisés"**, ajoute : - **Clé :** `Authorization` - **Valeur :** `Bearer aw_live_...` (ta clé) 6. **Ajouter** → trouve `astroway-hosted` dans la liste des connecteurs, active le commutateur. Pas besoin de redémarrer Claude Desktop. Clique sur `+` dans un nouveau chat — dans Connectors apparaîtra `astroway-hosted` avec les 630 outils + 12 prompts + 14 ressources. Pour Cline / Continue / Windsurf ou les anciennes versions de Claude Desktop / Cursor : ```json { "mcpServers": { "astroway-hosted": { "url": "https://mcp.astroway.info/mcp", "headers": { "Authorization": "Bearer aw_live_..." } } } } ``` Chemins vers les configurations : - **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) ou `.cursor/mcp.json` (dans l'espace de travail) - **Cline (VS Code) :** `.cline/mcp.json` dans l'espace de travail - **Continue :** `~/.continue/config.json` (bloc `mcpServers`) - **Windsurf :** `~/.codeium/windsurf/mcp_config.json` Après modification, redémarre complètement le client (Cmd+Q → rouvrir). ### Vérification ```bash curl https://mcp.astroway.info/health # {"status":"ok","version":"…","uptime_sec":…,"mcp_protocol_version":"2024-11-05"} ``` Dans le client — demande : *"Liste 5 noms d'outils AstroWay depuis astroway-hosted"*. Cela doit retourner des noms comme `astroway_western_chart`, `astroway_horoscope_daily`, `astroway_vedic_panchang_full`, … ### Limites de débit L'endpoint hébergé est protégé par une limitation à 3 niveaux : Cloudflare (couche anti-DDoS) + nginx `120 req/min/IP` + bucket en mémoire `60/60s/(IP+clé)`. Les vrais clients MCP (Claude Desktop, Cursor) ne s'approchent pas de ces limites — ils ne font pas de requêtes en rafale. Si ton automatisation / CI a besoin de > 120 req/min — utilise le mode **stdio** (pas de limites, il communique directement avec `api.astroway.info/v1/*` selon ta limite de débit tarifaire). ### Que faire si `mcp.astroway.info` est temporairement indisponible Si l'endpoint hébergé retourne une erreur 5xx, le client MCP verra une erreur lors de l'appel à `tools/list`. Cela **n'affecte pas** les clients en mode stdio — ils exécutent le package npm local qui communique directement avec `api.astroway.info/v1/*` sans couche hébergée intermédiaire. **Solution de repli pour les intégrations critiques :** ajoute un **deuxième serveur MCP** dans la configuration en mode stdio — le client l'utilisera automatiquement si l'hébergé ne répond pas à `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_..." } } } } ``` Le temps de disponibilité réel de l'endpoint hébergé est visible sur [status.astroway.info](https://status.astroway.info). Les incidents > 5 minutes font l'objet d'un postmortem publié sous 5 jours ouvrés (conformément à [/sla/](/sla/)). ## Stdio (npm) — pour le développement local [`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp) — un package npm qui s'exécute localement en tant que sous-processus. Un seul package npm, intégration native avec Claude Desktop, Cursor et tout client compatible MCP. ## Fonctionnement La liste des outils est générée **au moment de la construction** à partir de la spécification OpenAPI live ([api.astroway.info/v1/openapi.json](https://api.astroway.info/v1/openapi.json)). Chaque version du package récupère automatiquement tous les nouveaux endpoints — rien à maintenir manuellement. Chaque endpoint devient un outil de type : - `tools/list` retourne la description et le schéma d'entrée (avec un exemple de corps de requête) - `tools/call` effectue une requête HTTP POST vers `https://api.astroway.info/v1/` avec ta `ASTROWAY_API_KEY` - La réponse est renvoyée à l'agent sous forme de JSON structuré Chaque version est également livrée avec une attestation SLSA ([attestée par Sigstore](https://search.sigstore.dev/)) — cela garantit que le package npm est bien construit à partir du commit dans le dépôt public. ## Installation ### Claude Desktop (macOS) Ajoute dans `~/Library/Application Support/Claude/claude_desktop_config.json` : ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` Redémarre Claude Desktop. Dans la barre sous le chat apparaîtra une icône 🛠️ avec le nombre d'outils chargés. ### Cursor Ajoute dans `~/.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 La même commande `npx @astroway/mcp` fonctionne avec chaque client compatible MCP. La configuration est identique — seul le chemin du fichier change : ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` | Client | Chemin vers la configuration | |---|---| | **Cline** (VS Code) | `.cline/mcp.json` à la racine de l'espace de travail | | **Continue** | `~/.continue/config.json` (sous `mcpServers`) | | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | | **GitHub Copilot Chat (VS Code)** | flag de prévisualisation → `mcp.json` dans l'espace de travail | | **Extension VS Code MCP** | `~/.vscode/mcp.json` | ### Autres clients MCP Lance en tant que serveur stdio : ```bash ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp ``` ## Confidentialité — depuis v1.0.0+ Ce serveur MCP **n'envoie rien en retour à AstroWay** en dehors des appels API que tu lui demandes d'effectuer. Aucune télémétrie, aucun analytics, aucun commutateur opt-in/opt-out — silence par défaut. Les requêtes sortantes incluent deux en-têtes d'identification pour que le backend AstroWay puisse distinguer le trafic MCP des requêtes HTTP directes dans ses propres logs : - `User-Agent: astroway-mcp/ (Node/)` - `X-Astroway-Channel: mcp` Aucun de ces en-têtes ne contient d'ID de session, d'empreinte machine ou d'information personnelle. Il s'agit d'une sémantique standard de `User-Agent` — chaque outil CLI envoie des informations similaires. ## Inscription de sous-ensembles — depuis v1.0.0+ Si tu n'utilises qu'une partie du catalogue — enregistre un sous-ensemble pour garder la fenêtre contextuelle du LLM compacte : ```jsonc { "env": { "ASTROWAY_API_KEY": "aw_live_...", "ASTROWAY_TOOL_GROUPS": "western,vedic,relational", // seuls ces préfixes "ASTROWAY_READONLY": "1" // ignore les groupes ai/horoscope/reports (basés sur LLM, consomment des crédits) } } ``` Groupes courants : `western`, `vedic`, `tarot`, `numerology`, `hd` (Human Design), `relational` (synastrie/composite/davison), `prognostics` (transits/progressions/retours), `aspects`, `horary`, `geo`, `chinese`, `bazi`, `mayan`, `iching`, `runes`, `geomancy`. Lance `npx @astroway/mcp --list-tools` pour voir l'ensemble complet. `ASTROWAY_READONLY=1` ignore les trois groupes qui appellent en interne un LLM (`ai`, `horoscope`, `reports`) — utile si tu veux une astrologie purement mathématique sans dépenser de crédits pour la génération de texte. ## Engagement de stabilité — depuis v1.0.0+ - **Le catalogue est figé pendant la session.** 624 outils, 12 prompts, 14 ressources sont intégrés dans le package npm publié au moment de la construction — rien ne change pendant la connexion. Si ton client met en cache `tools/list` après le premier appel, il reste correct pour toute la session. - **Les identifiants des outils sont stables dans une version majeure.** Le nom sous `astroway__` ne sera pas renommé ou supprimé au sein de `v1.x` sans note de dépréciation dans `CHANGELOG.md` et une disponibilité parallèle minimale d'une version mineure. - **La forme des entrées des outils est stable dans une version mineure.** Les contraintes (regex, plage, enum) sont ajoutées dans les correctifs ; l'ajout d'un champ obligatoire nécessite une version mineure. - **Rafraîchir le catalogue se fait en réinstallant.** `npm i -g @astroway/mcp@latest` (ou la forme `npx -y @astroway/mcp` dans ta configuration) récupère l'ensemble actuel au prochain démarrage. ## Exemples de prompts Après avoir connecté le serveur, demande à l'IA : ### Carte natale > Calcule ma carte natale — né le 15 mars 1990, 14:30, Kiev. Décris le Soleil, la Lune, l'Ascendant et trouve les aspects serrés. Claude appellera l'outil `chart` avec tes paramètres, obtiendra un JSON structuré, et décrira la carte en mots. ### Transits > Quels transits significatifs des planètes lentes auront lieu sur ma carte natale au cours de l'année 2027 ? Claude effectue deux appels d'outils : d'abord `transits` (instantané actuel), puis `transit-calendar` (plage). Interprète les tendances. ### Mahadasha védique > Lance la Mahadasha Vimshottari pour une personne née le 22.07.1985 à 06:45 à Mumbai. Dans quelle période cette personne se trouve-t-elle actuellement ? Via l'outil `vedic/dashas/vimshottari/maha` — horodatage UTC précis de la période actuelle. ### Synastrie > Compare deux cartes : A — 10.06.1988 09:15 Londres, B — 22.11.1991 22:40 Berlin. Quels sont les aspects croisés les plus forts ? Outil `synastry` avec deux blocs `chart` + interprétation du score de compatibilité. ### Tarot > Tire 3 cartes Rider-Waite-Smith : Passé — Présent — Futur. Question : « dois-je accepter le nouveau travail ? ». Seed = 42. `tarot/rider-waite/spread` avec une graine fixe pour la reproductibilité. ## Liste de tous les outils Après la connexion, demande à Claude : > Liste tous les outils AstroWay. Ou depuis la ligne de commande : ```bash ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1 # (lance le serveur stdio ; les appels protocolaires de liste d'outils sont effectués par le client MCP) ``` ## Configuration | Variable | Par défaut | Description | Depuis la version | |---|---|---|---| | `ASTROWAY_API_KEY` | *(obligatoire)* | Live : `aw_live_...`. Sandbox : `aw_test_...`. | 0.1.0 | | `ASTROWAY_BASE_URL` | `https://api.astroway.info/v1` | Remplace pour les environnements auto-hébergés/staging. | 0.1.0 | | `ASTROWAY_TOOL_GROUPS` | *(tous les groupes)* | Préfixes séparés par des virgules pour limiter le catalogue (`western,vedic,relational`). | 1.0.0 | | `ASTROWAY_READONLY` | `0` | `1` ignore les groupes basés sur LLM (`ai`, `horoscope`, `reports`). | 1.0.0 | | `LOG_LEVEL` | `error` | `silent`/`error`/`warn`/`info`/`debug` — niveau de journalisation vers stderr. | 0.8.0 | | `LOG_FILE` | *(non écrit)* | Chemin vers un fichier pour dupliquer les logs. | 0.8.0 | | `MCP_FLAT_TOOLS` | `0` | `1` retourne les anciens noms plats pré-v0.9 (`chart` au lieu de `astroway_western_chart`). Legacy. | 0.9.0 | ## Pourquoi MCP et pas une intégration directe Un LLM générique (sans ancrage) dira *«quelque part en juillet, Saturne formera un trigone avec ta Jupiter »* — sans date précise, avec une marge de ±15 jours. **Un agent MCP** effectue `tool_use POST /v1/transits` et renvoie un horodatage UTC **à la seconde**, basé sur le Swiss Ephemeris réel. L'avantage ne vient pas du LLM, mais de la **garantie que les calculs sont réels** — pas inventés. ## Distribution du package - **Listing mcp.so :** [mcp.so/server/astroway-mcp/astroway](https://mcp.so/server/astroway-mcp/astroway) - **mcpservers.org :** en attente d'approbation (en mai 2026) - **awesome-mcp-servers (punkpeye) :** [PR #5972](https://github.com/punkpeye/awesome-mcp-servers/pull/5972) ## Liens - 📦 npm : [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) - 📘 Docs API : [/docs/api/](/docs/api/) - 🔑 Inscription : [/dashboard/sign-up](/dashboard/sign-up) - 💰 Tarification : [/pricing/](/pricing/) - 🌐 Dépôt public (MIT) : [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)