How do I install Elfa?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Elfa need an API key?

The publisher lists these environment variables: ELFA_API_KEY.

When was Elfa last checked?

Last checked 2026-11-07. Crypto social intelligence from X and Telegram, plus the Elfa Auto condition engine

Elfa MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y @elfa-ai/[email protected]

Credentials from the publisher

ELFA_API_KEY — Elfa API key from https://dev.elfa.ai

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1ELFA_API_KEY=<secret> claude mcp add ai.elfa-mcp -- npx -y @elfa-ai/mcp@4.10.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "ai.elfa-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "@elfa-ai/[email protected]"8      ],9      "env": {10        "ELFA_API_KEY": "<secret>"11      }12    }13  }14}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 4.10.0
API key

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

Elfa MCP

Model Context Protocol server for the Elfa API — API v3 events, positions and rankings across crypto and equities, Auto, a condition engine that watches the market and fires an action when your conditions are met, plus crypto social intelligence from X and Telegram.

Works with any MCP client, either signed in to the hosted server or running locally with an API key.

Install

Hosted, sign in with Elfa

Add https://mcp.elfa.ai/mcp as a remote MCP server in your client and approve it in your browser with your dev.elfa.ai account. No key to copy, nothing to install. If your client cannot sign in, run the server locally instead. Setup steps are in the MCP guide.

Local, API key

Get an API key at dev.elfa.ai. No install step — npx fetches the server on demand.

One click

Claude Desktop

Download elfa-mcp-<version>.mcpb from the latest release and open it. Claude Desktop installs it, prompts for your API key, and keeps it updated. Nothing else to configure.

Claude Code

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

Cursor, VS Code, Claude Desktop, and other clients

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

VS Code uses "servers" instead of "mcpServers". Everything else is the same.

Ask "what's trending in crypto right now?" to confirm it works.

Configuration

Variable	Required	Purpose
`ELFA_API_KEY`	yes	Authenticates every request
`ELFA_TIMEOUT`	no	Request timeout in ms, default `120000`
`ELFA_RETRIES`	no	Retries on failure, default `0`
`ELFA_MCP_MAX_RESPONSE_CHARS`	no	Response size ceiling, default `60000`
`ELFA_EXTRA_HEADERS`	no	JSON object of extra headers to send upstream, for proxies and non-production environments

Upstream requests identify themselves as User-Agent: elfa-mcp/<version> (<transport>; client=<app>). On stdio, <app> is the MCP client's name and version from the handshake; over HTTP, it is the connecting client's own User-Agent header. Set User-Agent in ELFA_EXTRA_HEADERS to send your own instead.

The timeout is high and retries are off on purpose. The interpretation endpoints are LLM-backed and can take over a minute, and they cost credits per attempt, so a silent retry would bill you again for a call you never saw. Raise ELFA_RETRIES only if you are calling the cheap measurement endpoints.

Some MCP clients apply their own timeout, often around 60 seconds. narratives and market_chat can exceed that; the request still completes and is still charged, even if the client gives up first.

Tools

16 tools, mapped to every documented /v2 and /v3 operation.

Tool	Mode	Cost	What it does
`api_status`	read	Free	Check API key tier, credit usage and remaining requests, and historyFrom, how far back events, market and calls read. Also confirms the API is reachable.
`entities`	read	Free on PAYG and Grow until 31 Oct 2026	Resolve a ticker, $cashtag, name, @handle, contract address, CoinGecko id, FIGI or CIK to the entity id that events and calls take. Matches exactly, it is not a search.
`events`	read	Free on PAYG and Grow until 31 Oct 2026	What is happening in crypto and equity markets. level=events for what happened and how prices reacted, level=storylines for one development threaded over days, level=arcs for storylines grouped into a larger movement. Searchable by topic.
`market`	read	Free on PAYG and Grow until 31 Oct 2026	Whole-market views for crypto or equities. view=mindshare ranks assets by share of attention, view=call_book is the crowd's long/short lean hour by hour, view=trending_contracts ranks contract addresses by how many posts pasted them.
`calls`	read	Free on PAYG and Grow until 31 Oct 2026	Positions accounts take in posts. level=calls for each post that takes or changes a position, level=episodes for each position from open to close with the author's track record, level=positioning for open longs and shorts on one asset now.
`top_accounts`	read	Free on PAYG and Grow until 31 Oct 2026	X accounts ranked by standing (how much other accounts engage with them) or, with metric, by their track record as callers (alphaScore, hitRate, avgReturn).
`auto_build`	read	1 plus LLM usage	Turn a plain-language monitoring request into an EQL query. Returns a draft to validate and activate, it does not activate anything itself.
`auto_validate`	read	Free	Check EQL syntax and get a cost estimate before activating, or check that a symbol has market data on a venue.
`auto_query`	read	Free	Read side of Auto: list queries, poll one query, and read its executions and LLM sessions.

Not exposed as tools:

chat-stream-v2 — A tool call returns one result, so streaming adds nothing. market_chat covers the same analysis.
auto-stream-queries-v2 — Long lived streams have no tool equivalent. Poll with auto_query.
auto-stream-query-v2 — Long lived streams have no tool equivalent. Poll with auto_query.

Some tools depend on the plan: today market_chat and the API v3 tools, which need a higher-tier plan than the free one. At startup (stdio) or per request (HTTP, cached for a minute per key), the server reads the key's scopes from /v2/key-status. A tool the plan doesn't include stays listed, but its description says it needs a higher-tier plan, and calling it returns the upgrade link without calling the API or spending credits. If the scopes can't be read within 3 seconds, every tool is listed as usual and the API decides.

Streaming endpoints stay available through the SDKs for applications that can consume SSE.

API v3

entities, events, market, calls and top_accounts read API v3: events, storylines and arcs; call books, mindshare and trending contracts; calls, call episodes and positioning; ranked accounts. They cover crypto and equities, are free on Pay-as-you-go and Grow plans until 31 October 2026, and are open to Enterprise keys.

Filters take entity ids, not tickers. Resolve an asset with entities first and reuse the id.
Times are unix seconds. Milliseconds are refused.
How far back a key reads depends on its plan. api_status returns it as historyFrom.

Where this differs from the raw API

The tools deliberately do not inherit every API default, because an agent pays for verbosity in context.

	API	Here	Why
`pageSize`	10 to 50 depending on endpoint, max 100	10	Page through rather than pull everything
`limit` on v3 tools	10 or 50 depending on endpoint, max 30 or 200	10	Page with `cursor` rather than pull everything
`speed` on chat	`expert`	`fast`	Cheaper by default, ask for `expert` when depth matters
Mention fields	full record	high signal fields	Pass `verbosity: "detailed"` for the rest
Large responses	returned whole	trimmed to fit, with a note	Keeps one call from filling the context window

Every value is still settable per call: pageSize accepts up to 100, and limit up to the endpoint's maximum.

Auto

Auto queries run unattended. Once armed, a query keeps evaluating and fires its action without asking again.

The flow is three steps:

auto_build — describe what to watch in plain language, get EQL back
auto_validate — check the syntax and get the credit cost
auto_query_write — activate it

Actions can notify you, call a webhook, message a Telegram bot, or run an LLM analysis.

There is no push channel over MCP. Poll auto_query with method=get, and wait for the returned pollAfterSeconds between calls.

Remote server

The same server runs over Streamable HTTP for hosted deployments:

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

It is stateless — no sessions, one server instance per request, safe behind a load balancer. Credentials come from the x-elfa-api-key request header, falling back to the environment, or from an OAuth sign-in (see below).

DNS rebinding protection is on by default. The server accepts only the loopback names it binds — localhost:PORT and 127.0.0.1:PORT — which covers the local run above and nothing else. Any deployment that answers on a different Host must list the values it serves:

ELFA_MCP_ALLOWED_HOSTS=mcp.example.com

That includes a public domain, a reverse proxy, and a container that maps the port to a different one than the server binds. A Host the list does not cover is rejected with 403.

Variable	Required	Purpose
`ELFA_MCP_TRANSPORT`	no	`http` to serve over Streamable HTTP, default `stdio`
`ELFA_MCP_HOST`	no	Bind address, default `127.0.0.1`
`ELFA_MCP_PORT`	no	Bind port, default `3000`
`ELFA_MCP_ALLOWED_HOSTS`	no	Comma separated `Host` allowlist, defaults to the loopback names bound
`ELFA_MCP_ALLOWED_ORIGINS`	no	Comma separated `Origin` allowlist
`ELFA_MCP_OPENAI_APPS_CHALLENGE`	no	Domain-verification token from OpenAI's plugin portal, served as plain text at `/.well-known/openai-apps-challenge`

Set ELFA_MCP_ALLOWED_ORIGINS as well when browsers call the server directly. It complements the host allowlist rather than replacing it: a rebound request is same origin, so it carries no Origin header for that list to check, and the Host header is the only one still naming the attacker's domain.

OAuth sign-in

A hosted server can let clients sign in through a browser instead of sending an API key. Set ELFA_MCP_AUTH=oauth and the server becomes an OAuth resource server under the MCP authorization spec:

A request with no credential gets 401 and a WWW-Authenticate challenge.
The challenge points the client to the protected-resource metadata at /.well-known/oauth-protected-resource/mcp.
That metadata names the authorization server, where the user signs in.
The client then sends Authorization: Bearer <token>.
The server checks the token against the authorization server's introspection endpoint. The endpoint answers with the Elfa API key the request runs as, so the token never reaches the Elfa API.

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	Required in OAuth mode	Purpose
`ELFA_MCP_AUTH`	yes	`oauth` to enable, default `apikey`
`ELFA_MCP_RESOURCE_URL`	yes	Canonical URL of this endpoint. Tokens must be issued for exactly this value
`ELFA_OAUTH_ISSUER`	yes	Authorization server listed in the metadata
`ELFA_OAUTH_INTROSPECTION_URL`	yes	Where tokens are checked
`ELFA_OAUTH_INTROSPECTION_TOKEN`	yes	Bearer sent to the introspection endpoint
`ELFA_OAUTH_SCOPES`	no	Comma separated scopes to advertise, default `elfa`

Notes:

An x-elfa-api-key header still works in OAuth mode.
ELFA_API_KEY is ignored in OAuth mode, so a caller with no credential never runs as the server's own key.
Valid tokens are cached for up to a minute, which bounds how long a revoked token keeps working.

Safety

api_status is the fastest way to tell an auth problem from a credit problem.

Mentions, news and narratives return third-party social text that anyone can write, events are written up from it, and the v3 tools carry third-party asset, account and channel names. The server marks it as untrusted in every response, and the server instructions tell the model to treat it as data. Keep that in mind before letting an agent chain from that content into auto_query_write.

Development

npm install
npm run build
npm run verify

npm run verify runs typecheck, tests, the spec drift check, and the docs check.

manifest.json maps every documented API operation to the tool that covers it. npm run check:drift fails if the API grows an operation the server does not handle. The tool table above is generated from the same file with npm run docs:tools.

License

MIT

Elfa

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Elfa?

Does Elfa need an API key?

What transport does Elfa use?

When was Elfa last checked?

Documentation

Elfa MCP

Install

Configuration

Tools

API v3

Where this differs from the raw API

Auto

Remote server

OAuth sign-in

Safety

Development

Links

License