Agenti AI e MCP

Stai costruendo un agente AI che deve eseguire veri calcoli astrologici invece di allucinare? AstroWay si collega a Claude (Anthropic), ChatGPT-4 (OpenAI), Llama 3.3 (Groq), DeepSeek, Google Gemini, Mistral - tramite MCP, llms.txt o chiamate HTTP dirette. Tre modi di integrazione - scegli in base al tipo di agente:

• llms.txt: file di discovery per agenti che leggono la documentazione (Cursor IDE, Windsurf, Claude nel browser, pipeline RAG personalizzate su LangChain/LlamaIndex).
• Server MCP: zero-code per Claude Desktop, Cursor IDE, Windsurf, VS Code (llm CLI) e qualsiasi client compatibile con MCP (incluso GPT con MCP tramite OpenAI Realtime API).
• HTTP API: accesso diretto dal tuo agente o framework (LangChain, LlamaIndex, AutoGen, CrewAI).

llms.txt: discovery per agenti AI

Il sito espone due file machine-readable nel formato llms.txt:

• /llms.txt: indice di tutte le pagine della documentazione raggruppate per sezioni (API Reference, Use Cases, Examples, Products). Piccolo, entra in qualsiasi context window.
• /llms-full.txt: l’intero contenuto della documentazione in un unico file plain-text. Adatto per l’indicizzazione offline in un database vettoriale o per un’iniezione una tantum nel context.

Quando usarli

Scenario	File
Cursor/Windsurf “leggi la docs di astroway e aiutami con l’integrazione”	/llms.txt (l’agente recupera da solo le sezioni necessarie)
Pipeline RAG propria / database vettoriale per un bot FAQ	/llms-full.txt (una fetch - l’intero corpus)
Claude/ChatGPT nel browser: “ecco la nostra API, costruisci un client”	/llms-full.txt incollato nel prompt
Agente in produzione con esecuzione di chiamate	Server MCP o HTTP API (vedi sotto)

Esempio: pull nel tuo agente

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.`;

Nota

I file vengono rigenerati automaticamente a ogni rilascio del sito. Freschezza garantita: la versione dell’API in fondo a /llms.txt corrisponde all’attuale deploy in produzione.

Server MCP (consigliato per Claude Desktop)

Il Model Context Protocol (MCP) è uno standard aperto per collegare strumenti ai modelli AI. Il server MCP di AstroWay fornisce 783 strumenti, uno per ogni operazione dell’API, oltre a 12 prompt e 14 risorse.

Configurazione per Claude Desktop

Aggiungi a claude_desktop_config.json:

{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["@astroway/mcp"],
      "env": {
        "ASTROWAY_API_KEY": "aw_live_your_key_here"
      }
    }
  }
}

Dopo il riavvio, Claude Desktop vedrà tutti i 783 strumenti. Per ridurre l’elenco, imposta ASTROWAY_TOOL_GROUPS oppure collega un server di dominio, vedi configurazione MCP.

Cosa può fare il server MCP

Strumento	Cosa fa
astroway_western_chart	Calcolo della carta natale
astroway_relational_synastry	Sinastria di due persone
astroway_horoscope_daily	Oroscopo giornaliero
astroway_ai_interpret_natal	Interpretazione AI della carta natale
astroway_hd_human_design	Carta HD completa
astroway_prognostics_transits	Transiti attuali

Elenco completo: 783 strumenti, l’intera API, ognuno con uno schema di risposta tipizzato.

Esempio di dialogo con Claude

Utente: Costruisci la carta natale di una persona nata il 14 luglio 1990 alle 14:30 a Kiev. Cosa significa il Sole in Cancro nella decima casa?

Claude: Usa astroway_western_chart per il calcolo, poi astroway_ai_interpret_placement per l’interpretazione. Restituisce le posizioni dei pianeti con dati reali e un’interpretazione significativa.

HTTP API

Per agenti AI senza supporto MCP - usa l’HTTP API direttamente.

Per la generazione di contenuti

TypeScript

// The AI agent calls /interpret/natal for an interpretation
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 { data: result } = await r.json();
// result.interpretation - ready AI interpretation
// result.disclaimer - disclaimer to display

Python

import os, requests

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()['data']
# result['interpretation'] - ready AI interpretation
# result['disclaimer']     - disclaimer to display

cURL

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

<?php
use GuzzleHttp\Client;

$aw = new Client(['base_uri' => '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)['data'];
// $result['interpretation'] - ready AI interpretation
// $result['disclaimer']     - disclaimer to display

Per calcoli + il tuo LLM

// 1. Get raw data from /chart (cheaper - 20 credits)
const chart = await fetch('https://api.astroway.info/v1/chart', { ... });
const { data } = await chart.json();

// 2. Pass the data to your own LLM
const prompt = `Interpret this natal chart: ${JSON.stringify(data.planets)}`;
const llmResponse = await myLLM.generate(prompt);

Consiglio

Se ti serve solo l’interpretazione - usa /interpret/* (50 crediti, testo pronto). Se vuoi controllare il prompt - prendi /chart (20 crediti) e passa i dati al tuo LLM.

Scenari

Assistente astrologico personale

Server MCP + Claude/ChatGPT. L’utente chiede - l’agente calcola e interpreta. Budget: piano Free per uso personale.

Bot di contenuti per i social

Generazione giornaliera di oroscopi per i 12 segni tramite /horoscope/daily. 12 richieste al giorno = 240 crediti. Piano Free con ampio margine.

Piattaforma di AI-coaching

/interpret/natal + /interpret/transits per ogni cliente. 100 clienti/giorno = 10 000 crediti/giorno. Piano Pro.

Avvio rapido → La prima richiesta in 5 minuti

Horoscope API Interpretazioni AI e oroscopi

Tariffe Dal gratuito all'Enterprise