Elfa AI

A Elfa é nosso agente financeiro principal, alimentado por nossa stack de inteligência em tempo real (Iris). A Iris sintetiza sinais de dados de mercado sociais, on-chain e off-chain, e então rastreia seus efeitos de segunda e terceira ordem, para que os agentes ajam com maior contexto.

GitHub

Experimente este MCPPatrocinado

Documentação

Elfa MCP

Servidor do Model Context Protocol para a API Elfa — inteligência social de criptomoedas do X e Telegram, além do Auto, um mecanismo de condições que monitora o mercado e dispara uma ação quando suas condições são atendidas.

Funciona com qualquer cliente MCP: Claude Code, Claude Desktop, Cursor, VS Code, Codex e qualquer outra ferramenta que fale MCP.

Instalação

Obtenha uma chave de API em dev.elfa.ai. Sem etapa de instalação — o npx busca o servidor sob demanda.

Um clique

Claude Desktop

Baixe o elfa-mcp-<version>.mcpb do último lançamento e abra-o. O Claude Desktop instala, solicita sua chave de API e mantém tudo atualizado. Nada mais para configurar.

Claude Code

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

Cursor, VS Code, Claude Desktop e outros clientes

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

O VS Code usa "servers" em vez de "mcpServers". Todo o resto é igual.

Pergunte "o que está em alta em cripto agora?" para confirmar que funciona.

Configuração

Variável	Obrigatória	Finalidade
`ELFA_API_KEY`	sim	Autentica cada requisição
`ELFA_TIMEOUT`	não	Timeout de requisição em ms, padrão `120000`
`ELFA_RETRIES`	não	Tentativas em caso de falha, padrão `0`
`ELFA_MCP_MAX_RESPONSE_CHARS`	não	Limite de tamanho da resposta, padrão `60000`
`ELFA_EXTRA_HEADERS`	não	Objeto JSON com cabeçalhos extras para enviar upstream, para proxies e ambientes não produtivos

O timeout é alto e as tentativas estão desativadas de propósito. Os endpoints de interpretação são baseados em LLM e podem levar mais de um minuto, além de custarem créditos por tentativa, então uma nova tentativa silenciosa cobraria novamente por uma chamada que você nunca viu. Aumente ELFA_RETRIES apenas se estiver chamando os endpoints de medição baratos.

Alguns clientes MCP aplicam seu próprio timeout, geralmente em torno de 60 segundos. narratives e market_chat podem exceder isso; a requisição ainda é concluída e ainda é cobrada, mesmo que o cliente desista antes.

Ferramentas

11 ferramentas, mapeadas para cada operação documentada da /v2.

Ferramenta	Modo	Custo	O que faz
`api_status`	leitura	Grátis	Verifica o nível da chave de API, uso de créditos e requisições restantes. Também confirma se a API está acessível.
`mentions`	leitura	1 por chamada	Menções sociais do X e Telegram. mode=top classifica as menções de um ticker por engajamento, mode=search filtra por palavra-chave ou conta, mode=news retorna o feed de notícias do token, que são posts do X de contas marcadas como fontes de notícias, e não artigos de veículos de imprensa.
`trending`	leitura	1 por chamada	O que está ganhando atenção social. scope=tokens para tickers, scope=contracts_twitter ou scope=contracts_telegram para endereços de contratos.
`narratives`	leitura	5 por chamada	Análise narrativa escrita com links de fontes. scope=market extrai narrativas do mercado inteiro, scope=keywords resume eventos para palavras-chave específicas.
`account_stats`	leitura	1 por chamada	Estatísticas de seguidores inteligentes e engajamento para uma conta do X. Legado: ainda funciona, mas será removido em 28 de outubro de 2026.
`market_chat`	leitura	Varia conforme a velocidade	Solicite análise de mercado escrita. Suporta chat conversacional, visão macro, resumo rápido, introdução de token, análise de token e análise de conta.
`auto_build`	leitura	1 mais uso de LLM	Transforma uma solicitação de monitoramento em linguagem natural em uma consulta EQL. Retorna um rascunho para validar e ativar; não ativa nada por conta própria.
`auto_validate`	leitura	Grátis	Verifica a sintaxe EQL e obtém uma estimativa de custo antes de ativar, ou verifica se um símbolo tem dados de mercado em uma plataforma.
`auto_query`	leitura	Grátis	Lado de leitura do Auto: lista consultas, consulta uma consulta e lê suas execuções e sessões de LLM.
`auto_query_write`	escrita	5 mais uso de LLM para criar, grátis para cancelar ou excluir	Ativa, cancela ou exclui uma consulta Auto. Consultas ativadas são executadas sem supervisão e disparam sua ação quando as condições são atendidas.
`auto_draft`	escrita	Grátis, exceto convert, que custa o mesmo que criar uma consulta	Gerencia rascunhos Auto inativos. Rascunhos não são avaliados até serem convertidos em uma consulta ativa.

Não expostos como ferramentas:

chat-stream-v2 — Uma chamada de ferramenta retorna um resultado, então streaming não acrescenta nada. market_chat cobre a mesma análise.
auto-stream-queries-v2 — Streams de longa duração não têm equivalente em ferramenta. Consulte com auto_query.
auto-stream-query-v2 — Streams de longa duração não têm equivalente em ferramenta. Consulte com auto_query.

Algumas ferramentas dependem do plano: hoje, market_chat, que precisa de um plano de nível superior ao gratuito. Na inicialização (stdio) ou por requisição (HTTP, em cache por um minuto por chave), o servidor lê os escopos da chave de /v2/key-status. Uma ferramenta que o plano não inclui permanece listada, mas sua descrição diz que ela precisa de um plano de nível superior, e chamá-la retorna o link de upgrade sem chamar a API ou gastar créditos. Se os escopos não puderem ser lidos em 3 segundos, todas as ferramentas são listadas normalmente e a API decide.

Endpoints de streaming permanecem disponíveis através dos SDKs para aplicações que podem consumir SSE.

Onde isso difere da API bruta

As ferramentas deliberadamente não herdam todos os padrões da API, porque um agente paga pela verbosidade no contexto.

	API	Aqui	Por quê
`pageSize`	10 a 50 dependendo do endpoint, máximo 100	10	Pagine em vez de puxar tudo
`speed` no chat	`expert`	`fast`	Mais barato por padrão, peça `expert` quando profundidade importar
Campos de menção	registro completo	campos de alto sinal	Passe `verbosity: "detailed"` para o restante
Respostas grandes	retornadas inteiras	ajustadas para caber, com uma nota	Evita que uma chamada preencha a janela de contexto

Todo valor ainda é configurável por chamada, e pageSize aceita até 100.

Auto

Consultas Auto são executadas sem supervisão. Uma vez armada, uma consulta continua avaliando e dispara sua ação sem perguntar novamente.

O fluxo tem três etapas:

auto_build — descreva o que monitorar em linguagem natural, receba EQL de volta
auto_validate — verifique a sintaxe e obtenha o custo em créditos
auto_query_write — ative

As ações podem notificá-lo, chamar um webhook, enviar mensagem para um bot do Telegram ou executar uma análise de LLM.

Não há canal push via MCP. Consulte auto_query com method=get e aguarde o pollAfterSeconds retornado entre as chamadas.

Servidor remoto

O mesmo servidor roda sobre Streamable HTTP para implantações hospedadas:

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

Ele é stateless — sem sessões, uma instância de servidor por requisição, seguro atrás de um balanceador de carga. As credenciais vêm do cabeçalho de requisição x-elfa-api-key, com fallback para o ambiente, ou de um login OAuth (veja abaixo).

A proteção contra rebinding de DNS está ativada por padrão. O servidor aceita apenas os nomes de loopback aos quais ele se vincula — localhost:PORT e 127.0.0.1:PORT — o que cobre a execução local acima e nada mais. Qualquer implantação que responda em um Host diferente deve listar os valores que atende:

ELFA_MCP_ALLOWED_HOSTS=mcp.example.com

Isso inclui um domínio público, um proxy reverso e um contêiner que mapeia a porta para uma diferente daquela à qual o servidor se vincula. Um Host que a lista não cobre é rejeitado com 403.

Variável	Obrigatória	Finalidade
`ELFA_MCP_TRANSPORT`	não	`http` para servir via Streamable HTTP, padrão `stdio`
`ELFA_MCP_HOST`	não	Endereço de bind, padrão `127.0.0.1`
`ELFA_MCP_PORT`	não	Porta de bind, padrão `3000`
`ELFA_MCP_ALLOWED_HOSTS`	não	Lista de permissão de `Host` separada por vírgulas, padrão para os nomes de loopback vinculados
`ELFA_MCP_ALLOWED_ORIGINS`	não	Lista de permissão de `Origin` separada por vírgulas

Defina ELFA_MCP_ALLOWED_ORIGINS também quando navegadores chamarem o servidor diretamente. Ele complementa a lista de permissão de hosts em vez de substituí-la: uma requisição com rebinding é de mesma origem, então não carrega cabeçalho Origin para essa lista verificar, e o cabeçalho Host é o único que ainda nomeia o domínio do atacante.

Login OAuth

Um servidor hospedado pode permitir que clientes façam login pelo navegador em vez de enviar uma chave de API. Defina ELFA_MCP_AUTH=oauth e o servidor se torna um servidor de recursos OAuth sob a especificação de autorização MCP:

Uma requisição sem credencial recebe 401 e um desafio WWW-Authenticate.
O desafio aponta o cliente para os metadados do recurso protegido em /.well-known/oauth-protected-resource/mcp.
Esses metadados nomeiam o servidor de autorização, onde o usuário faz login.
O cliente então envia Authorization: Bearer <token>.
O servidor verifica o token no endpoint de introspecção do servidor de autorização. O endpoint responde com a chave de API Elfa sob a qual a requisição roda, então o token nunca chega à API 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

Variável	Obrigatória no modo OAuth	Finalidade
`ELFA_MCP_AUTH`	sim	`oauth` para ativar, padrão `apikey`
`ELFA_MCP_RESOURCE_URL`	sim	URL canônica deste endpoint. Os tokens devem ser emitidos exatamente para este valor
`ELFA_OAUTH_ISSUER`	sim	Servidor de autorização listado nos metadados
`ELFA_OAUTH_INTROSPECTION_URL`	sim	Onde os tokens são verificados
`ELFA_OAUTH_INTROSPECTION_TOKEN`	sim	Bearer enviado ao endpoint de introspecção
`ELFA_OAUTH_SCOPES`	não	Escopos separados por vírgulas para divulgar, padrão `elfa`

Observações:

Um cabeçalho x-elfa-api-key ainda funciona no modo OAuth.
ELFA_API_KEY é ignorado no modo OAuth, então um chamador sem credencial nunca roda como a chave do próprio servidor.
Tokens válidos são armazenados em cache por até um minuto, o que limita por quanto tempo um token revogado continua funcionando.

Segurança

api_status é a maneira mais rápida de distinguir um problema de autenticação de um problema de créditos.

Menções, notícias e narrativas retornam texto social de terceiros que qualquer pessoa pode escrever. O servidor marca esse conteúdo como não confiável em cada resposta, e as instruções do servidor dizem ao modelo para tratá-lo como dados. Tenha isso em mente antes de permitir que um agente encadeie esse conteúdo em auto_query_write.

Desenvolvimento

npm install
npm run build
npm run verify

npm run verify executa verificação de tipos, testes, verificação de desvio de especificação e verificação de documentação.

manifest.json mapeia cada operação documentada da API para a ferramenta que a cobre. npm run check:drift falha se a API ganhar uma operação que o servidor não trata. A tabela de ferramentas acima é gerada a partir do mesmo arquivo com npm run docs:tools.

Licença

MIT