Agenti AI e MCP

Stai costruendo un agente AI che deve fare vere e proprie calcoli astrologici invece di allucinazioni? 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 per integrarlo: 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 con LangChain/LlamaIndex).
• Server MCP — zero-code per Claude Desktop, Cursor IDE, Windsurf, VS Code (llm CLI) e qualsiasi client compatibile con MCP (inclusi GPT con MCP tramite OpenAI Realtime API).
• HTTP API — chiamata diretta dal tuo agente o framework (LangChain, LlamaIndex, AutoGen, CrewAI).

llms.txt — discovery per agenti AI

Il sito espone due file machine-readable in 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 — contenuto completo della documentazione in un unico file plain-text. Ideale per l’indicizzazione offline in un database vettoriale o per un singolo caricamento nel context.

Quando usarlo

Scenario	File
Cursor/Windsurf: «leggi la docs di AstroWay e aiutami con l’integrazione»	/llms.txt (l’agente recupererà automaticamente le sezioni necessarie)
Pipeline RAG personalizzata / database vettoriale per un chatbot FAQ	/llms-full.txt (un’unica fetch — l’intero corpus)
Claude/ChatGPT nel browser: «ecco la nostra API, costruisci un client»	Incolla /llms-full.txt nel prompt
Agente in produzione con esecuzione di chiamate	Server MCP o HTTP API (vedi sotto)

Esempio: pull nella tua applicazione

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 ad ogni rilascio del sito. La freschezza è garantita: la versione dell’API alla fine di /llms.txt corrisponde al deployment in produzione corrente.

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 offre 25 strumenti per calcoli e interpretazioni astrologiche.

Configurazione per Claude Desktop

Aggiungi a claude_desktop_config.json:

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

Dopo il riavvio di Claude Desktop, vedrai 25 strumenti astrologici.

Cosa può fare il server MCP

Strumento	Funzione
natal_chart	Calcolo della carta natale
synastry	Sinastria tra due persone
daily_horoscope	Oroscopo giornaliero
interpret_natal	Interpretazione AI della carta natale
human_design	Carta completa di Human Design
transits	Transiti attuali

Lista completa: 25 strumenti che coprono i principali calcoli e interpretazioni AI.

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 nel 10° casa?

Claude: Usa natal_chart per il calcolo, poi interpret_placement per l’interpretazione. Restituisce le posizioni planetarie con dati reali e un’interpretazione significativa.

HTTP API

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

Per la generazione di contenuti

TypeScript

// L'agente AI chiama /interpret/natal per l'interpretazione
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 — interpretazione AI pronta
// result.disclaimer — disclaimer da mostrare

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()
# result['text'] — interpretazione AI pronta
# result['disclaimer'] — disclaimer da mostrare

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);
// $result['text']       — interpretazione AI pronta
// $result['disclaimer'] — disclaimer da mostrare

Per calcoli + LLM personalizzato

// 1. Ottieni i dati grezzi tramite /chart (più economico — 20 crediti)
const chart = await fetch('https://api.astroway.info/v1/chart', { ... });
const data = await chart.json();

// 2. Passa i dati al tuo 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.

Casi d’uso

Assistente astrologico personale

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

Chatbot per contenuti social

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

Piattaforma di coaching AI

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

Guida rapida → Prima richiesta in 5 minuti

Horoscope API Interpretazioni AI e oroscopi

Piani tariffari Da Free a Enterprise