# Agents IA et MCP
Tu construis un agent IA qui doit effectuer de **vrais calculs astrologiques** au lieu de générer des hallucinations ? AstroWay s’intègre à **Claude (Anthropic), ChatGPT-4 (OpenAI), Llama 3.3 (Groq), DeepSeek, Google Gemini, Mistral** — via MCP, llms.txt ou des appels HTTP directs. Trois méthodes d’intégration, à toi de choisir selon le type d’agent :
- **`llms.txt`** — fichiers de découverte pour les agents qui lisent la documentation (Cursor IDE, Windsurf, Claude dans le navigateur, pipelines RAG personnalisés avec LangChain/LlamaIndex).
- **Serveur MCP** — solution *zero-code* pour Claude Desktop, Cursor IDE, Windsurf, VS Code (via llm CLI) et tout client compatible MCP (y compris GPT avec MCP via l’OpenAI Realtime API).
- **HTTP API** — appel direct depuis ton propre agent ou framework (LangChain, LlamaIndex, AutoGen, CrewAI).
## llms.txt — découverte pour les agents IA
Le site expose deux fichiers lisibles par machine au format [llms.txt](https://llmstxt.org/) :
- **[`/llms.txt`](https://api.astroway.info/llms.txt)** — index de toutes les pages de la documentation, regroupées par sections (API Reference, Use Cases, Examples, Products). Léger, il tient dans n’importe quelle *context window*.
- **[`/llms-full.txt`](https://api.astroway.info/llms-full.txt)** — contenu complet de la documentation en un seul fichier texte brut. Idéal pour l’indexation hors ligne dans une base vectorielle ou pour un import ponctuel dans le contexte.
### Quand les utiliser ?
| Scénario | Fichier |
|---|---|
| Cursor/Windsurf : *« lis la doc AstroWay et aide-moi à intégrer l’API »* | `/llms.txt` (l’agent récupère lui-même les sections pertinentes) |
| Pipeline RAG personnalisé / base vectorielle pour un bot FAQ | `/llms-full.txt` (un seul fetch = tout le corpus) |
| Claude/ChatGPT dans le navigateur : *« voici notre API, construis un client »* | Coller `/llms-full.txt` dans le prompt |
| Agent en production avec exécution d’appels | Serveur MCP ou HTTP API (voir ci-dessous) |
### Exemple : récupération dans ton agent
```ts
const docs = await fetch('https://api.astroway.info/llms-full.txt').then(r => r.text());
const systemPrompt = `You are an integration assistant for AstroWay API.
Documentation:
${docs}
When the user asks how to do X, return a working code snippet using their API key.`;
```
## Serveur MCP (recommandé pour Claude Desktop)
Le *Model Context Protocol* (MCP) est un standard ouvert pour connecter des outils aux modèles d’IA. Le serveur MCP d’AstroWay propose **25 outils** pour les calculs et interprétations astrologiques.
### Configuration pour Claude Desktop
Ajoute dans `claude_desktop_config.json` :
```json
{
"mcpServers": {
"astroway": {
"command": "npx",
"args": ["@astroway/mcp"],
"env": {
"ASTROWAY_API_KEY": "aw_live_your_key_here"
}
}
}
}
```
Après un redémarrage de Claude Desktop, tu verras **25 outils astrologiques** disponibles.
### Que fait le serveur MCP ?
| Outil | Fonction |
|---|---|
| `natal_chart` | Calcul d’un thème natal |
| `synastry` | Synastrie entre deux personnes |
| `daily_horoscope` | Horoscope quotidien |
| `interpret_natal` | Interprétation IA d’un thème natal |
| `human_design` | Carte complète en Human Design |
| `transits` | Transits actuels |
Liste complète : **25 outils** couvrant les calculs de base et les interprétations IA.
### Exemple de dialogue avec Claude
> **Utilisateur :** Construis un thème natal pour une personne née le 14 juillet 1990 à 14h30 à Kiev. Que signifie le Soleil en Cancer en maison X ?
>
> **Claude :** *Utilise `natal_chart` pour le calcul, puis `interpret_placement` pour l’interprétation. Retourne les positions planétaires avec des données réelles et une interprétation pertinente.*
## HTTP API
Pour les agents IA sans support MCP, utilise directement l’HTTP API.
### Pour la génération de contenu
```ts
// L’agent IA appelle /interpret/natal pour l’interprétation
const r = await fetch('https://api.astroway.info/v1/interpret/natal', {
method: 'POST',
headers: {
'X-Api-Key': process.env.ASTROWAY_API_KEY!,
'Content-Type': 'application/json',
},
body: JSON.stringify({
date: '1990-07-14',
time: '14:30:00',
timezoneOffset: 3,
latitude: 50.4501,
longitude: 30.5234,
}),
});
const result = await r.json();
// result.text — interprétation IA prête à l’emploi
// result.disclaimer — mention légale à afficher
```
```python
r = requests.post(
'https://api.astroway.info/v1/interpret/natal',
headers={'X-Api-Key': os.environ['ASTROWAY_API_KEY']},
json={
'date': '1990-07-14',
'time': '14:30:00',
'timezoneOffset': 3,
'latitude': 50.4501,
'longitude': 30.5234,
},
)
result = r.json()
# result['text'] — interprétation IA prête à l’emploi
# result['disclaimer'] — mention légale à afficher
```
```bash frame="terminal"
curl -X POST https://api.astroway.info/v1/interpret/natal \
-H "X-Api-Key: $ASTROWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"date": "1990-07-14",
"time": "14:30:00",
"timezoneOffset": 3,
"latitude": 50.4501,
"longitude": 30.5234
}'
```
```php
'https://api.astroway.info/v1/']);
$r = $aw->post('interpret/natal', [
'headers' => ['X-Api-Key' => getenv('ASTROWAY_API_KEY')],
'json' => [
'date' => '1990-07-14',
'time' => '14:30:00',
'timezoneOffset' => 3,
'latitude' => 50.4501,
'longitude' => 30.5234,
],
]);
$result = json_decode($r->getBody(), true);
// $result['text'] — interprétation IA prête à l’emploi
// $result['disclaimer'] — mention légale à afficher
```
### Pour les calculs + ton propre LLM
```ts
// 1. Récupère les données brutes via /chart (moins cher — 20 crédits)
const chart = await fetch('https://api.astroway.info/v1/chart', { ... });
const data = await chart.json();
// 2. Transmets les données à ton LLM
const prompt = `Interpret this natal chart: ${JSON.stringify(data.planets)}`;
const llmResponse = await myLLM.generate(prompt);
```
## Cas d’usage
### Assistant astrologique personnel
Serveur MCP + Claude/ChatGPT. L’utilisateur pose une question, l’agent calcule et interprète. Budget : forfait *Free* pour un usage personnel.
### Bot de contenu pour les réseaux sociaux
Génération quotidienne d’horoscopes pour les 12 signes via `/horoscope/daily`. 12 requêtes/jour = 240 crédits. Le forfait *Free* offre une grande marge.
### Plateforme de coaching IA
`/interpret/natal` + `/interpret/transits` pour chaque client. 100 clients/jour = 10 000 crédits/jour. Forfait *Pro*.