Elfa AI

Elfa MCP

Servidor del Model Context Protocol para la API de Elfa — inteligencia social cripto de X y Telegram, además de Auto, un motor de condiciones que observa el mercado y dispara una acción cuando se cumplen tus condiciones.

Funciona con cualquier cliente MCP: Claude Code, Claude Desktop, Cursor, VS Code, Codex y cualquier otra cosa que hable MCP.

Instalación

Obtén una clave de API en dev.elfa.ai. Sin paso de instalación — npx obtiene el servidor bajo demanda.

Un clic

Claude Desktop

Descarga elfa-mcp-<version>.mcpb desde la última versión y ábrelo. Claude Desktop lo instala, solicita tu clave de API y lo mantiene actualizado. No hay nada más que configurar.

Claude Code

claude mcp add elfa --env ELFA_API_KEY=your-key -- npx -y @elfa-ai/mcp

Cursor, VS Code, Claude Desktop y otros clientes

{
  "mcpServers": {
    "elfa": {
      "command": "npx",
      "args": ["-y", "@elfa-ai/mcp"],
      "env": {
        "ELFA_API_KEY": "your-key"
      }
    }
  }
}

VS Code usa "servers" en lugar de "mcpServers". Todo lo demás es igual.

Pregunta "¿qué está en tendencia en cripto ahora mismo?" para confirmar que funciona.

Configuración

Variable	Obligatoria	Propósito
ELFA_API_KEY	sí	Autentica cada solicitud
ELFA_TIMEOUT	no	Tiempo de espera de la solicitud en ms, por defecto 120000
ELFA_RETRIES	no	Reintentos en caso de fallo, por defecto 0
ELFA_MCP_MAX_RESPONSE_CHARS	no	Límite de tamaño de respuesta, por defecto 60000
ELFA_EXTRA_HEADERS	no	Objeto JSON de cabeceras adicionales para enviar aguas arriba, para proxies y entornos que no son de producción

El tiempo de espera es alto y los reintentos están desactivados a propósito. Los endpoints de interpretación están respaldados por LLM y pueden tardar más de un minuto, y cuestan créditos por intento, por lo que un reintento silencioso te facturaría de nuevo una llamada que nunca viste. Aumenta ELFA_RETRIES solo si estás llamando a los endpoints de medición baratos.

Algunos clientes MCP aplican su propio tiempo de espera, a menudo alrededor de 60 segundos. narratives y market_chat pueden superar eso; la solicitud aún se completa y aún se cobra, incluso si el cliente se rinde primero.

Herramientas

11 herramientas, mapeadas a cada operación documentada de /v2.

Herramienta	Modo	Coste	Qué hace
api_status	lectura	Gratis	Comprueba el nivel de la clave de API, el uso de créditos y las solicitudes restantes. También confirma que la API es accesible.
mentions	lectura	1 por llamada	Menciones sociales de X y Telegram. mode=top clasifica las menciones de un ticker por interacción, mode=search filtra por palabra clave o cuenta, mode=news devuelve el feed de noticias del token, que son publicaciones de X de cuentas etiquetadas como fuentes de noticias en lugar de artículos de medios de comunicación.
trending	lectura	1 por llamada	Lo que está ganando atención social. scope=tokens para tickers, scope=contracts_twitter o scope=contracts_telegram para direcciones de contrato.
narratives	lectura	5 por llamada	Análisis narrativo escrito con enlaces a fuentes. scope=market extrae narrativas de todo el mercado, scope=keywords resume eventos para palabras clave específicas.
account_stats	lectura	1 por llamada	Estadísticas de seguidores inteligentes y de interacción para una cuenta de X. Legado: todavía funciona, pero se eliminará el 28 de octubre de 2026.
market_chat	lectura	Varía según la velocidad	Solicita análisis de mercado escrito. Admite chat conversacional, visión macro, resumen rápido, introducción de token, análisis de token y análisis de cuenta.
auto_build	lectura	1 más uso de LLM	Convierte una solicitud de monitoreo en lenguaje natural en una consulta EQL. Devuelve un borrador para validar y activar, no activa nada por sí mismo.
auto_validate	lectura	Gratis	Comprueba la sintaxis de EQL y obtén una estimación de coste antes de activar, o comprueba que un símbolo tiene datos de mercado en un lugar.
auto_query	lectura	Gratis	Lado de lectura de Auto: lista consultas, consulta una consulta y lee sus ejecuciones y sesiones de LLM.
auto_query_write	escritura	5 más uso de LLM para crear, gratis para cancelar o eliminar	Activa, cancela o elimina una consulta de Auto. Las consultas activadas se ejecutan sin supervisión y disparan su acción cuando se cumplen las condiciones.
auto_draft	escritura	Gratis, excepto convertir que cuesta lo mismo que crear una consulta	Gestiona borradores de Auto inactivos. Los borradores no se evalúan hasta que se convierten en una consulta activa.

No expuestos como herramientas:

• chat-stream-v2 — Una llamada a herramienta devuelve un resultado, por lo que el streaming no añade nada. market_chat cubre el mismo análisis.
• auto-stream-queries-v2 — Los flujos de larga duración no tienen equivalente de herramienta. Consulta con auto_query.
• auto-stream-query-v2 — Los flujos de larga duración no tienen equivalente de herramienta. Consulta con auto_query.

Algunas herramientas dependen del plan: hoy market_chat, que necesita un plan de nivel superior al gratuito. Al inicio (stdio) o por solicitud (HTTP, almacenado en caché durante un minuto por clave), el servidor lee los alcances de la clave desde /v2/key-status. Una herramienta que el plan no incluye permanece listada, pero su descripción dice que necesita un plan de nivel superior, y llamarla devuelve el enlace de actualización sin llamar a la API ni gastar créditos. Si los alcances no se pueden leer en 3 segundos, cada herramienta se lista como de costumbre y la API decide.

Los endpoints de streaming permanecen disponibles a través de los SDKs para aplicaciones que pueden consumir SSE.

Dónde esto difiere de la API cruda

Las herramientas deliberadamente no heredan cada valor predeterminado de la API, porque un agente paga por la verbosidad en contexto.

	API	Aquí	Por qué
pageSize	10 a 50 según el endpoint, máximo 100	10	Pagina en lugar de traer todo
speed en chat	expert	fast	Más barato por defecto, pide expert cuando la profundidad importa
Campos de mención	registro completo	campos de alta señal	Pasa verbosity: "detailed" para el resto
Respuestas grandes	devueltas completas	recortadas para caber, con una nota	Evita que una llamada llene la ventana de contexto

Cada valor sigue siendo configurable por llamada, y pageSize acepta hasta 100.

Auto

Las consultas de Auto se ejecutan sin supervisión. Una vez armada, una consulta sigue evaluando y dispara su acción sin preguntar de nuevo.

El flujo tiene tres pasos:

1. auto_build — describe qué observar en lenguaje natural, obtén EQL de vuelta
2. auto_validate — comprueba la sintaxis y obtén el coste en créditos
3. auto_query_write — actívala

Las acciones pueden notificarte, llamar a un webhook, enviar un mensaje a un bot de Telegram o ejecutar un análisis de LLM.

No hay canal push a través de MCP. Consulta auto_query con method=get y espera el pollAfterSeconds devuelto entre llamadas.

Servidor remoto

El mismo servidor se ejecuta sobre Streamable HTTP para despliegues alojados:

ELFA_MCP_TRANSPORT=http ELFA_MCP_PORT=3000 npx -y @elfa-ai/mcp

No tiene estado — sin sesiones, una instancia de servidor por solicitud, seguro detrás de un balanceador de carga. Las credenciales provienen de la cabecera de solicitud x-elfa-api-key, con respaldo al entorno, o de un inicio de sesión OAuth (ver más abajo).

La protección contra rebinding de DNS está activada por defecto. El servidor solo acepta los nombres de bucle local a los que se vincula — localhost:PORT y 127.0.0.1:PORT — lo que cubre la ejecución local anterior y nada más. Cualquier despliegue que responda en un Host diferente debe listar los valores que sirve:

ELFA_MCP_ALLOWED_HOSTS=mcp.example.com

Eso incluye un dominio público, un proxy inverso y un contenedor que mapea el puerto a uno diferente del que el servidor vincula. Un Host que la lista no cubre se rechaza con 403.

Variable	Obligatoria	Propósito
ELFA_MCP_TRANSPORT	no	http para servir sobre Streamable HTTP, por defecto stdio
ELFA_MCP_HOST	no	Dirección de vinculación, por defecto 127.0.0.1
ELFA_MCP_PORT	no	Puerto de vinculación, por defecto 3000
ELFA_MCP_ALLOWED_HOSTS	no	Lista de permitidos de Host separada por comas, por defecto los nombres de bucle local vinculados
ELFA_MCP_ALLOWED_ORIGINS	no	Lista de permitidos de Origin separada por comas

Establece ELFA_MCP_ALLOWED_ORIGINS también cuando los navegadores llaman al servidor directamente. Complementa la lista de permitidos de hosts en lugar de reemplazarla: una solicitud rebotada es del mismo origen, por lo que no lleva cabecera Origin para que esa lista la compruebe, y la cabecera Host es la única que todavía nombra el dominio del atacante.

Inicio de sesión OAuth

Un servidor alojado puede permitir que los clientes inicien sesión a través de un navegador en lugar de enviar una clave de API. Establece ELFA_MCP_AUTH=oauth y el servidor se convierte en un servidor de recursos OAuth bajo la especificación de autorización MCP:

1. Una solicitud sin credencial obtiene 401 y un desafío WWW-Authenticate.
2. El desafío apunta al cliente a los metadatos del recurso protegido en /.well-known/oauth-protected-resource/mcp.
3. Esos metadatos nombran el servidor de autorización, donde el usuario inicia sesión.
4. El cliente entonces envía Authorization: Bearer <token>.
5. El servidor comprueba el token contra el endpoint de introspección del servidor de autorización. El endpoint responde con la clave de API de Elfa con la que se ejecuta la solicitud, por lo que el token nunca llega a la API de Elfa.

ELFA_MCP_TRANSPORT=http \
ELFA_MCP_AUTH=oauth \
ELFA_MCP_RESOURCE_URL=https://mcp.example.com/mcp \
ELFA_OAUTH_ISSUER=https://auth.example.com \
ELFA_OAUTH_INTROSPECTION_URL=https://auth.example.com/introspect \
ELFA_OAUTH_INTROSPECTION_TOKEN=... \
ELFA_MCP_ALLOWED_HOSTS=mcp.example.com \
npx -y @elfa-ai/mcp

Variable	Obligatoria en modo OAuth	Propósito
ELFA_MCP_AUTH	sí	oauth para habilitar, por defecto apikey
ELFA_MCP_RESOURCE_URL	sí	URL canónica de este endpoint. Los tokens deben emitirse exactamente para este valor
ELFA_OAUTH_ISSUER	sí	Servidor de autorización listado en los metadatos
ELFA_OAUTH_INTROSPECTION_URL	sí	Dónde se comprueban los tokens
ELFA_OAUTH_INTROSPECTION_TOKEN	sí	Bearer enviado al endpoint de introspección
ELFA_OAUTH_SCOPES	no	Alcances separados por comas para anunciar, por defecto elfa

Notas:

• Una cabecera x-elfa-api-key todavía funciona en modo OAuth.
• ELFA_API_KEY se ignora en modo OAuth, por lo que un llamador sin credencial nunca se ejecuta con la clave propia del servidor.
• Los tokens válidos se almacenan en caché hasta por un minuto, lo que limita cuánto tiempo sigue funcionando un token revocado.

Seguridad

api_status es la forma más rápida de distinguir un problema de autenticación de un problema de créditos.

Las menciones, noticias y narrativas devuelven texto social de terceros que cualquiera puede escribir. El servidor lo marca como no confiable en cada respuesta, y las instrucciones del servidor le dicen al modelo que lo trate como datos. Tenlo en cuenta antes de dejar que un agente encadene desde ese contenido hacia auto_query_write.

Desarrollo

npm install
npm run build
npm run verify

npm run verify ejecuta verificación de tipos, pruebas, la verificación de desviación de especificación y la verificación de documentación.

manifest.json mapea cada operación de API documentada a la herramienta que la cubre. npm run check:drift falla si la API crece con una operación que el servidor no maneja. La tabla de herramientas anterior se genera desde el mismo archivo con npm run docs:tools.

Enlaces

• Documentación
• Claves de API
• SDK de TypeScript

Licencia

MIT