ai.elfaPublished by elfa.aiv4.10.0Updated Nov 7, 2026
Crypto social intelligence from X and Telegram, plus the Elfa Auto condition engine
Elfa gives an assistant crypto and equity market intelligence from X and Telegram social data, plus an Auto condition engine that fires actions when…
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
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.
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
[Add to Cursor] [Add to VS Code]
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
Cursor, VS Code, Claude Desktop, and other clients
VS Code uses "servers" instead of "mcpServers". Everything else is the same.
Ask "what's trending in crypto right now?" to confirm it works.
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.
16 tools, mapped to every documented /v2 and /v3 operation.
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.getAccountSmartStats-v2 — Deprecated and not maintained, so no tool wraps it. To rank accounts, use top_accounts; mentions with mode=search returns per-post engagement metrics with the posting account.Some tools depend on the plan: today market_chat, which needs a higher-tier plan than the free one, and the API v3 tools on a key whose scopes leave them out. 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.
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 and are open to every plan. Each call costs credits, priced per endpoint on the pricing page.
entities first and reuse the id.api_status returns it as historyFrom.The tools deliberately do not inherit every API default, because an agent pays for verbosity in context.
Every value is still settable per call: pageSize accepts up to 100, and limit up to the endpoint's maximum.
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 backauto_validate — check the syntax and get the credit costauto_query_write — activate itActions 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.
The same server runs over Streamable HTTP for hosted deployments:
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:
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.
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.
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:
401 and a WWW-Authenticate challenge./.well-known/oauth-protected-resource/mcp.Authorization: Bearer <token>.Notes:
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.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.
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.
MIT
Source: README.md at commit 4ef1b35
API key status
Check the Elfa API key tier, credit usage and remaining requests, and confirm the API is reachable. Free. historyFrom is the earliest time, in unix seconds, the events, market and calls tools read on this plan.
Takes no parameters.
Entities
Turn a ticker, $cashtag, name, @handle, contract address, CoinGecko id, FIGI or CIK into the entity id that events and calls take.. It matches exactly, it is not a search: a prefix or a misspelling returns nothing. A ticker is not unique, so take the first row and check its name, or narrow with entityType. Forms of an asset share one family id where known: WBTC and cbBTC are Bitcoin. Resolve once and reuse the id.
qrequiredlimitcursorentityTypeEvents
What is happening in crypto and equity markets, written up from posts across many sources.. level=events: what happened, what it names, how prices reacted where measured (impacts is empty on most events), and the posts behind it. level=storylines: the events of one development, threaded over days. level=arcs: storylines grouped into a larger movement. Search any level by topic with q, filter by asset with entityIds from the entities tool, or fetch up to 30 you hold with ids. Not returned: post text, a sentiment score or a price.
qtoidsfromsortarcIdlevellimitordercursorstatusnotable+9 moreMarket
Whole-market views, no asset needed.. view=mindshare ranks assets by share of attention over a period, with hot on those heating up. view=call_book is the crowd's long/short lean, one bar per hour plus a live tick: read crowdingPercentile rather than longShare, since the accounts lean long almost always. view=trending_contracts ranks contract addresses by how many posts pasted them, crypto only, and the unnamed ones are often the ones worth watching.
tofromviewlimitordercursormarketperiodminMentionsCalls
What accounts are doing: positions taken in posts on X and Telegram.. level=calls: each post that opened, added to, trimmed, reaffirmed, reversed, closed or stopped out of a position. level=episodes: each position from open to close, with entry and exit prices and the author's track record. level=positioning: open longs and shorts on one asset right now. level=episodes with status=open and from set to now reads what every matching account holds right now. Not returned: post text or a recommendation.
toidsfromlevellimitordercursorhandlestatusentityIddirectionentityIds+1 moreTop accounts
X accounts ranked by standing (how much other accounts engage with them) or, with metric, by their track record as callers.. Standing measures attention, not accuracy; track is null for an account that has never opened a position. For the best callers use metric=alphaScore, not avgReturn, which a few big wins or a rally can top. Track metrics rank only accounts with at least 20 scored positions, over every position since late June 2026; scoredEpisodes is the number of positions behind each account's track metrics.
limitordercursormetricAuto query builder
Turn a plain-language monitoring request into an EQL query. Costs 1 credit plus LLM usage. This only drafts the query: nothing runs until it is activated. Say what to watch, the threshold, and what should happen when it fires. It drafts tweet conditions only for accounts in Elfa's real-time set (included), not for other X accounts.
speedmessagerequiredsessionIdValidate Auto query
Check EQL syntax and get the estimated cost of activating a query. Free. tweetAccounts lists the X account behind each tweet condition: billing=per_post accounts cost creditsPerPost for every post from the account (not replies or reposts), matched or not, while the query runs, on top of estimatedCredits. followAccounts lists the X account behind each x_follow_made or x_follow_overlap condition: billing=per_day accounts cost creditsPerDay for each UTC day their follows are read while the query runs, also on top of estimatedCredits. Pass either an inline query or a draftId. method=symbol instead checks that a symbol has market data on a venue, which price and ta conditions need.
querytitlemethodsymboldraftIdexchangedescriptionRead Auto queries
Read side of Auto. Free. method=list browses queries, method=get polls one query and returns its latest evaluation, plus failure when it failed with a recorded reason, method=executions and method=execution show what fired, method=sessions and method=session return the LLM analysis attached to a query. There is no push channel here, poll with method=get and respect pollAfterSeconds.
typelimitmethodrequiredoffsetsearchstatusqueryIdsessionIdexecutionIdWrite Auto queries
Activate, cancel or delete an Auto query. Creating costs 5 credits plus LLM usage, cancel and delete are free. An activated query runs unattended and fires its action without asking again. Per-post X accounts in its tweet conditions and per-day accounts in its x_follow_made or x_follow_overlap conditions are billed on top while it runs.
querytitlemethodrequiredqueryIddescriptionRead Auto drafts
Read side of Auto drafts. Free. method=list browses saved drafts, method=get returns one draft. A draft is an Auto query parked without activating it: it never evaluates and never fires.
limitmethodrequiredoffsetsearchstatusdraftIdWrite Auto drafts
Create, update, delete or activate an Auto draft. method=upsert parks a query as a draft without activating it; drafts never evaluate and never fire. method=delete removes a draft. method=convert activates a draft as a live query, which runs unattended and fires its action without asking again, and costs the same as creating a query. upsert and delete are free.
querytitlemethodrequireddraftIddescriptionMentions
Social mentions from X and Telegram. 1 credit per call. Returns engagement metrics and a link per post, not the post text. mode=top ranks one ticker's mentions by engagement. mode=search filters by keywords or by account. mode=news returns the token news feed, which is X posts from accounts tagged as news sources rather than articles from news outlets.
tofrommoderequiredpagelimitcursortickercoinIdsrepostskeywordspageSizeverbosity+3 moreTrending
What is gaining social attention right now. 1 credit per call. scope=tokens returns tickers ranked by mention volume with the change against the previous window. scope=contracts_twitter and scope=contracts_telegram return trending contract addresses.
tofrompagescopepageSizetimeWindowminMentionsNarratives
Written narrative analysis with source links, for when counts are not enough. 5 credits per call. scope=market extracts the narratives moving the market. scope=keywords summarises events for keywords you supply, and can take over a minute to return.
tofromscopekeywordstimeFramesearchTypetimeWindowmaxNarrativesmaxTweetsPerNarrativeMarket chat
Ask Elfa for written market analysis grounded in its social data. Costs credits and varies by speed, so fast is the cheaper option. Pass sessionId from a previous reply to continue the same conversation. The reply includes sources: links to the posts and pages the research read (links only, not their text), so you can cite or check them.
chainspeedsymbolmessageusernamesessionIduseMemoryanalysisTypecontractAddress90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
claude mcp add elfa --env ELFA_API_KEY=your-key -- npx -y @elfa-ai/mcp{ "mcpServers": { "elfa": { "command": "npx", "args": ["-y", "@elfa-ai/mcp"], "env": { "ELFA_API_KEY": "your-key" } } }}ELFA_MCP_TRANSPORT=http ELFA_MCP_PORT=3000 npx -y @elfa-ai/mcpELFA_MCP_ALLOWED_HOSTS=mcp.example.comELFA_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/mcpnpm installnpm run buildnpm run verify