Conecta tu agente en cuatro pasos.
Para Claude, ChatGPT o Codex, se recomienda OAuth porque puede exponer de forma segura las herramientas de HumanDesign.ai permitidas para el usuario con sesión iniciada.
1. Añade el endpoint alojado
Endpoint
https://mcp.humandesign.ai/Elige Remote HTTP o Streamable HTTP. No añadas /mcp otra vez: el endpoint canónico es la raíz del dominio.
2. Autentícate
Usa la acción MCP Authenticate o Connect del cliente y completa el inicio de sesión de HumanDesign.ai en el navegador. Los usuarios de Claude Code pueden ejecutar claude mcp login human-design-ai; los usuarios de Codex pueden ejecutar codex mcp login human_design_ai.
Si solo necesitas las seis herramientas de cálculo y referencia, sigue disponible una clave API mediante autenticación Bearer o X-Api-Key autenticación.
3. Descubre tus herramientas
JSON-RPC
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}El descubrimiento es gratuito. La visibilidad de las herramientas OAuth sigue las concesiones de capacidades derivadas por el servidor, la membresía Free/Individual/Personal/Pro, el rol del espacio de trabajo, la propiedad y los permisos del producto. La visibilidad con clave API sigue el plan API independiente Free/Creator/Startup/Business.
4. Empieza por tu carta principal
Pide al agente que llame a chart_get_primary. Si no existe una carta principal, los miembros Free, Individual, Personal y Pro pueden usar chart_generate: primero revisa los datos de nacimiento normalizados y la vista previa de una unidad; después confirma la ejecución. La carta guardada se determina por la propiedad de la cuenta, nunca buscando un nombre como «Kyle» o «Mi carta». Para leer cartas autorizadas de otras personas se requiere Personal o Pro.
La conexión, initialize, ping, tools/list, las lecturas de la biblioteca, las comprobaciones de estado y la representación de cartas existentes no consumen créditos. Calcular una carta principal nueva consume exactamente una unidad de cálculo; representarla no añade otro cargo.
Cómo se garantizan los cálculos
El agente no calcula la carta por su cuenta. HumanDesign.ai valida la fecha, la ubicación, la zona horaria IANA y el contexto del horario de verano antes de consumir el cupo, y después devuelve el resultado versionado de su servicio de cálculo. Las ubicaciones ambiguas y los datos no válidos generan un error claro sin gastar una unidad. Si se desconoce la hora de nacimiento, el servicio registra el mediodía local y advierte que pueden variar los detalles de la carta sensibles a la hora.
Reintentos seguros de cálculo
Las herramientas MCP que consumen unidades generate_chart, generate_composite_charty get_transits requieren una idempotencyKey. Reutiliza la misma clave con argumentos normalizados idénticos para un reintento previsto y usa una clave nueva para tareas nuevas. Un reintento coincidente no consume cupo adicional y puede volver a calcular el resultado de forma determinista; no reproduce byte a byte una respuesta almacenada. Las llamadas MCP de tránsito requieren una fecha explícita para que cada reintento se refiera al mismo instante. Los clientes REST directos y Agent HTTP pueden enviar Idempotency-Key en las operaciones acotadas sin transmisión que lo admiten. Sigue siendo opcional durante el despliegue de compatibilidad; sin ella, las llamadas no pueden deduplicar un reintento de transporte. Las operaciones por lotes y SSE rechazan las claves de reintento indicadas por el cliente y quedan fuera de este contrato de deduplicación.
Prueba del protocolo sin procesar
Los desarrolladores que utilizan una clave API pueden inicializar y llamar directamente a una herramienta de cálculo:
Inicializar
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {
"name": "my-agent",
"version": "1.0.0"
}
}
}Llamada de cálculo
{
"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"
}
}
}Elige tu cliente
Claude · Codex · Cursor · VS Code · Descargas de plugins