Collega il tuo agente in quattro passaggi.
Per Claude, ChatGPT o Codex, OAuth è la connessione consigliata perché può esporre in modo sicuro gli strumenti HumanDesign.ai consentiti per l’utente autenticato.
1. Aggiungi l’endpoint ospitato
Endpoint
https://mcp.humandesign.ai/Scegli remote HTTP o Streamable HTTP. Non aggiungere /mcp di nuovo: l’endpoint canonico è la radice del dominio.
2. Autenticati
Usa l’azione MCP Authenticate o Connect del client e completa l’accesso HumanDesign.ai nel browser. Gli utenti di Claude Code possono eseguire claude mcp login human-design-ai; gli utenti di Codex possono eseguire codex mcp login human_design_ai.
Se ti servono solo i sei strumenti di calcolo e riferimento, la chiave API è ancora disponibile tramite autenticazione Bearer o X-Api-Key autenticazione.
3. Scopri i tuoi strumenti
JSON-RPC
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}L’individuazione è gratuita. La visibilità degli strumenti OAuth segue le concessioni di capacità derivate dal server, l’appartenenza Free/Individual/Personal/Pro, il ruolo nello spazio di lavoro, la proprietà e le autorizzazioni del prodotto. La visibilità tramite chiave API segue il piano API separato Free/Creator/Startup/Business.
4. Inizia con il tuo grafico principale
Chiedi all’agente di chiamare chart_get_primary. Se non esiste un grafico principale, gli iscritti ai piani Free, Individual, Personal e Pro possono usare chart_generate: prima verifica i dati di nascita normalizzati e l’anteprima dell’unità singola, poi conferma l’esecuzione. Il grafico salvato viene individuato in base alla proprietà dell’account, mai cercando un nome come “Kyle” o “My Chart”. Per leggere i grafici autorizzati di altre persone è necessario Personal o Pro.
Connessione, initialize, ping, tools/list, la consultazione della libreria, i controlli di stato e la visualizzazione di grafici esistenti non consumano crediti. Un nuovo calcolo del grafico principale consuma esattamente un’unità di calcolo; la visualizzazione non comporta un secondo addebito.
Come funziona l’affidabilità dei calcoli
L’agente non calcola direttamente il grafico. HumanDesign.ai convalida data, località, fuso orario IANA e ora legale prima di consumare la quota, quindi restituisce il risultato versionato del proprio servizio di calcolo. Località ambigue e dati non validi generano un errore chiaro senza consumare unità. Se l’ora di nascita è sconosciuta, il servizio registra l’uso delle 12:00 locali e avvisa che i dettagli del grafico sensibili all’orario potrebbero differire.
Nuovi tentativi di calcolo sicuri
Gli strumenti MCP che consumano quota generate_chart, generate_composite_charte get_transits richiedono una idempotencyKey. Riutilizza la stessa chiave con argomenti normalizzati identici per un singolo tentativo intenzionale e usa una nuova chiave per le nuove operazioni. Un tentativo corrispondente non consuma altra quota e può ricalcolare il risultato in modo deterministico; non riproduce byte per byte una risposta memorizzata. Le chiamate MCP di transito richiedono una data esplicita, così ogni tentativo si riferisce sempre allo stesso momento. I client REST diretti e Agent HTTP possono inviare Idempotency-Key nelle operazioni supportate, limitate e non in streaming; durante la fase di compatibilità resta facoltativa, quindi le chiamate che non la includono non possono deduplicare un nuovo tentativo di trasporto. Batch e SSE rifiutano le chiavi di ripetizione fornite dal chiamante e non rientrano nel contratto di deduplicazione dei tentativi.
Test del protocollo grezzo
Gli sviluppatori che usano una chiave API possono inizializzare e chiamare direttamente uno strumento di calcolo:
Inizializzazione
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {
"name": "my-agent",
"version": "1.0.0"
}
}
}Chiamata di calcolo
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "generate_chart",
"arguments": {
"birthDateTime": "1990-05-15T14:30:00",
"timezone": "America/New_York",
"detailLevel": "core",
"idempotencyKey": "chart-1990-05-15-v1"
}
}
}Scegli il tuo client
Claude · Codex · Cursor · VS Code · Download dei plugin