{
  "markdown": "# Elfa MCP\n\nModel Context Protocol server for the [Elfa API](https://docs.elfa.ai) — crypto social intelligence from X and Telegram, plus **Auto**, a condition engine that watches the market and fires an action when your conditions are met.\n\nWorks with any MCP client: Claude Code, Claude Desktop, Cursor, VS Code, Codex, and anything else that speaks MCP.\n\n## Install\n\nGet an API key at [dev.elfa.ai](https://dev.elfa.ai). No install step — `npx` fetches the server on demand.\n\n**One click**\n\n[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-000000?style=flat-square)](cursor://anysphere.cursor-deeplink/mcp/install?name=elfa&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBlbGZhLWFpL21jcCJdLCJlbnYiOnsiRUxGQV9BUElfS0VZIjoiJHtpbnB1dDplbGZhQXBpS2V5fSJ9fQ==)\n[![Add to VS Code](https://img.shields.io/badge/Add%20to-VS%20Code-0098FF?style=flat-square)](https://vscode.dev/redirect/mcp/install?name=elfa&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40elfa-ai%2Fmcp%22%5D%2C%22env%22%3A%7B%22ELFA_API_KEY%22%3A%22%24%7Binput%3AelfaApiKey%7D%22%7D%7D)\n\n**Claude Desktop**\n\nDownload `elfa-mcp-<version>.mcpb` from the [latest release](https://github.com/elfa-ai/mcp/releases/latest) and open it. Claude Desktop installs it, prompts for your API key, and keeps it updated. Nothing else to configure.\n\n**Claude Code**\n\n```bash\nclaude mcp add elfa --env ELFA_API_KEY=your-key -- npx -y @elfa-ai/mcp\n```\n\n**Cursor, VS Code, Claude Desktop, and other clients**\n\n```json\n{\n  \"mcpServers\": {\n    \"elfa\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@elfa-ai/mcp\"],\n      \"env\": {\n        \"ELFA_API_KEY\": \"your-key\"\n      }\n    }\n  }\n}\n```\n\nVS Code uses `\"servers\"` instead of `\"mcpServers\"`. Everything else is the same.\n\nAsk *\"what's trending in crypto right now?\"* to confirm it works.\n\n## Configuration\n\n| Variable | Required | Purpose |\n| --- | --- | --- |\n| `ELFA_API_KEY` | yes | Authenticates every request |\n| `ELFA_TIMEOUT` | no | Request timeout in ms, default `120000` |\n| `ELFA_RETRIES` | no | Retries on failure, default `0` |\n| `ELFA_MCP_MAX_RESPONSE_CHARS` | no | Response size ceiling, default `60000` |\n| `ELFA_EXTRA_HEADERS` | no | JSON object of extra headers to send upstream, for proxies and non-production environments |\n\nThe 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.\n\nSome 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.\n\n## Tools\n\n<!-- tools:start -->\n\n11 tools, mapped to every documented `/v2` operation.\n\n| Tool | Mode | Cost | What it does |\n| --- | --- | --- | --- |\n| `api_status` | read | Free | Check API key tier, credit usage and remaining requests. Also confirms the API is reachable. |\n| `mentions` | read | 1 per call | Social mentions from X and Telegram. mode=top ranks a ticker's mentions by engagement, mode=search filters by keyword or account, mode=news returns the token news feed, which is X posts from accounts tagged as news sources rather than articles from news outlets. |\n| `trending` | read | 1 per call | What is gaining social attention. scope=tokens for tickers, scope=contracts_twitter or scope=contracts_telegram for contract addresses. |\n| `narratives` | read | 5 per call | Written narrative analysis with source links. scope=market extracts market-wide narratives, scope=keywords summarises events for specific keywords. |\n| `account_stats` | read | 1 per call | Smart follower and engagement stats for an X account. Legacy: it still works, but will be removed on 28 October 2026. |\n| `market_chat` | read | Varies by speed | Ask for written market analysis. Supports conversational chat, macro overview, quick summary, token intro, token analysis and account analysis. |\n| `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. |\n| `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. |\n| `auto_query` | read | Free | Read side of Auto: list queries, poll one query, and read its executions and LLM sessions. |\n| `auto_query_write` | write | 5 plus LLM usage to create, free to cancel or delete | Activate, cancel or delete an Auto query. Activated queries run unattended and fire their action when conditions are met. |\n| `auto_draft` | write | Free, except convert which costs the same as creating a query | Manage inactive Auto drafts. Drafts do not evaluate until converted into an active query. |\n\nNot exposed as tools:\n\n- `getMarketEvents-v2` — Available only to select Enterprise customers, and the published operation takes no parameters. Contact sales@elfa.ai for access.\n- `chat-stream-v2` — A tool call returns one result, so streaming adds nothing. market_chat covers the same analysis.\n- `auto-stream-queries-v2` — Long lived streams have no tool equivalent. Poll with auto_query.\n- `auto-stream-query-v2` — Long lived streams have no tool equivalent. Poll with auto_query.\n\n<!-- tools:end -->\n\nStreaming endpoints stay available through the [SDKs](https://docs.elfa.ai) for applications that can consume SSE.\n\n### Where this differs from the raw API\n\nThe tools deliberately do not inherit every API default, because an agent pays for verbosity in context.\n\n| | API | Here | Why |\n| --- | --- | --- | --- |\n| `pageSize` | 10 to 50 depending on endpoint, max 100 | 10 | Page through rather than pull everything |\n| `speed` on chat | `expert` | `fast` | Cheaper by default, ask for `expert` when depth matters |\n| Mention fields | full record | high signal fields | Pass `verbosity: \"detailed\"` for the rest |\n| Large responses | returned whole | trimmed to fit, with a note | Keeps one call from filling the context window |\n\nEvery value is still settable per call, and `pageSize` accepts up to 100.\n\n## Auto\n\nAuto queries run unattended. Once armed, a query keeps evaluating and fires its action without asking again.\n\nThe flow is three steps:\n\n1. `auto_build` — describe what to watch in plain language, get EQL back\n2. `auto_validate` — check the syntax and get the credit cost\n3. `auto_query_write` — activate it\n\nActions can notify you, call a webhook, message a Telegram bot, or run an LLM analysis.\n\nThere is no push channel over MCP. Poll `auto_query` with `method=get`, and wait for the returned `pollAfterSeconds` between calls.\n\n## Remote server\n\nThe same server runs over Streamable HTTP for hosted deployments:\n\n```bash\nELFA_MCP_TRANSPORT=http ELFA_MCP_PORT=3000 npx -y @elfa-ai/mcp\n```\n\nIt 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.\n\nDNS 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:\n\n```bash\nELFA_MCP_ALLOWED_HOSTS=mcp.example.com\n```\n\nThat 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.\n\n| Variable | Required | Purpose |\n| --- | --- | --- |\n| `ELFA_MCP_TRANSPORT` | no | `http` to serve over Streamable HTTP, default `stdio` |\n| `ELFA_MCP_HOST` | no | Bind address, default `127.0.0.1` |\n| `ELFA_MCP_PORT` | no | Bind port, default `3000` |\n| `ELFA_MCP_ALLOWED_HOSTS` | no | Comma separated `Host` allowlist, defaults to the loopback names bound |\n| `ELFA_MCP_ALLOWED_ORIGINS` | no | Comma separated `Origin` allowlist |\n\nSet `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.\n\n## Safety\n\n`api_status` is the fastest way to tell an auth problem from a credit problem.\n\n\nMentions, news and narratives return third-party social text that anyone can write. 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`.\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm run verify\n```\n\n`npm run verify` runs typecheck, tests, the spec drift check, and the docs check.\n\n`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`.\n\n## Links\n\n- [Documentation](https://docs.elfa.ai)\n- [API keys](https://dev.elfa.ai)\n- [TypeScript SDK](https://www.npmjs.com/package/@elfa-ai/sdk)\n\n## License\n\nMIT\n",
  "bytes": 9301,
  "sha": "4b8e09b85e10f3edfca22e84fedfb356420a2a328c4bb8e76dfbbfe71d6aa9ba",
  "repo_slug": "elfa-ai/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_elfa_mcp_a777223e/readme"
}