eterna-mcp-agent-starter
Eterna MCP Agent Starter
Build an AI trading agent on Eterna Hybrid Exchange in under 30 minutes — using Claude (MCP), the official CLI, or sandboxed TypeScript strategies. Ships with its own MCP server: fee estimator, venue comparison, setup guides and guarded agent prompts that work without an account, plus an authenticated bridge to the official Eterna MCP endpoint.
Eterna is a no-KYC perpetual futures exchange with flat fees (0.014% maker / 0.035% taker), CEX-grade liquidity routed from Bybit, and native AI-agent tooling: an MCP server, a CLI, and a managed TypeScript sandbox with an injected eterna.* SDK.
Affiliate disclosure: links to Eterna in this repo use referral code
Steve. Signing up through them costs you nothing extra — fees are identical — and supports this project.
Why Eterna for agents
Eterna | Typical setup (direct CEX API) | |
KYC | None — wallet auth | Full KYC |
Taker fee | Flat 0.035% | 0.045%+ before volume tiers |
Maker fee | Flat 0.014% | 0.015%+ |
Agent access | Native MCP server + CLI + sandbox SDK | Roll your own REST/WS client |
Agent safety | Isolated sub-account, no withdrawal rights | API key scoping varies |
Liquidity | $10B+ routed from Bybit order books, <200ms | Depends on venue |
Run your own numbers: Eterna vs Hyperliquid fee calculator · full comparison.
Related MCP server: AgentBroker MCP Server
Path 0 — Run the starter MCP server
A stdio MCP server that any client (Claude Desktop, Claude Code, Cursor, Windsurf, Glama) can launch. It needs no credentials to start.
{
"mcpServers": {
"eterna-starter": {
"command": "npx",
"args": ["-y", "github:stevevstd-oss/eterna-mcp-agent-starter"]
}
}
}Tool | Needs account | What it does |
| No | Monthly fees for a volume and maker/taker mix, plus EHX credited via EHX Payback |
| No | Same volume across Eterna, Hyperliquid, Bybit, Binance — with sources |
| No | Step-by-step for |
| No | Guarded trading-agent prompt (1% risk cap, mandatory SL/TP, approval gate) |
| No | Whether the bridge is active and how to authenticate |
Official Eterna tools | Yes | Bridged from |
Bridge mode. Set ETERNA_ACCESS_TOKEN in the server's env, or run npx @eterna-hybrid-exchange/cli login once — the server reads ~/.eterna/credentials.json (override with ETERNA_CONFIG_DIR) and refreshes it when needed. Every tool exposed by the official endpoint then appears next to the local ones.
# From source
git clone https://github.com/stevevstd-oss/eterna-mcp-agent-starter && cd eterna-mcp-agent-starter
npm install && npm run build && npm test
# Docker
docker build -t eterna-mcp-agent-starter .
docker run -i --rm -e ETERNA_ACCESS_TOKEN eterna-mcp-agent-starterEnvironment variables: ETERNA_ACCESS_TOKEN (optional), ETERNA_CONFIG_DIR (default ~/.eterna), ETERNA_MCP_URL (default https://mcp.eterna.exchange/mcp), ETERNA_AUTH_ISSUER (default https://ai-auth.eterna.exchange).
Path 1 — Claude with MCP (no code)
Sign up at ehx.app (wallet signature, ~2 minutes, no KYC).
In Claude: Customize → Connectors → Add Custom Connector.
Name it
Eterna, set the server URL to:https://mcp.eterna.exchange/mcpClick Add → Connect, sign in, and Authorize.
Keep Needs Approval on at first — approve each trade manually until you trust your prompts.
Works with claude.ai, Claude Desktop, and Claude Code. See docs/claude-setup.md for details and the generic MCP client config.
Path 2 — Official CLI
# Authenticate (browser OAuth, or device code over SSH)
npx @eterna-hybrid-exchange/cli login
# Check auth and endpoint status
npx @eterna-hybrid-exchange/cli status
# Balance and open positions
npx @eterna-hybrid-exchange/cli balance
npx @eterna-hybrid-exchange/cli positions
# Browse the sandbox SDK reference
npx @eterna-hybrid-exchange/cli sdk --search "place order"
npx @eterna-hybrid-exchange/cli sdk --detail fullCredentials are stored in ~/.eterna/credentials.json and auto-refreshed. See docs/cli-setup.md.
Path 3 — TypeScript strategies in the sandbox
Your code runs in Eterna's managed Deno sandbox with the eterna.* SDK injected — no API client to build, no keys in your code.
# Run a strategy file
npx @eterna-hybrid-exchange/cli execute examples/first-session.ts
# Or pipe code directly
echo 'const balance = await eterna.getBalance(); return balance;' \
| npx @eterna-hybrid-exchange/cli execute -Starter strategies in examples/:
first-session.ts— read balance, positions, and a ticker; no orders placed. Run this first.account-snapshot.ts— a compact account + market report your agent can call on a schedule.
Agent prompts to pair with the MCP connector are in prompts/.
Safety model (read this)
The MCP/CLI agent operates an isolated sub-account: it can trade but cannot withdraw funds. Your master account keeps custody.
Start with Needs Approval in Claude; switch to Always Allow only for strategies you have watched run.
Fund the sub-account only with what the strategy needs.
Perpetual futures with leverage can lose money quickly. Nothing in this repo is financial advice. See SECURITY.md.
Docs
docs/claude-setup.md — Claude / MCP client setup
docs/cli-setup.md — CLI reference and auth flows
docs/fees.md — fee schedule and comparison, with sources
src/ — the MCP server (
index.tstools and bridge,fees.tsfee model,auth.tstoken resolution)
Official resources
Eterna AI landing: https://ai.eterna.exchange/
MCP endpoint:
https://mcp.eterna.exchange/mcpOfficial monorepo: https://github.com/EternaHybridExchange/eterna-ai
CLI repo: https://github.com/EternaHybridExchange/eterna-cli
Referral program details: https://eterna.exchange/blog/eterna-referral-program-earn-from-the-volume-you-bring
30-minute agent tutorial: https://eterna.exchange/blog/build-your-ai-trading-agent-with-eterna-mcp-in-less-than-30-minutes
Disclaimer
Community project, not affiliated with or endorsed by Eterna Hybrid Exchange. SDK method names and commands follow the official docs at the time of writing — verify with npx @eterna-hybrid-exchange/cli sdk before trading real funds. Trading perpetual futures involves substantial risk of loss.
MIT © 2026
Available Tools
5 toolseterna_agent_promptA
Return a guarded prompt template for a trading agent on Eterna (risk caps, mandatory stop loss, approval gates). Use it as the system or session prompt once the Eterna tools are connected. No credentials needed.
| Name | Required | Description | Default |
|---|---|---|---|
| variant | No | Which template to return. | session-bootstrap |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the guardrail nature of the output, mentions risk caps/stop loss/approval gates, and states no credentials are needed. It does not explicitly state there are no side effects, but for a prompt-returning tool this is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences. The first states what is returned and its content highlights; the second gives the intended usage and a credential note. Every word earns its place, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter, no-output-schema tool, the description covers what is returned, when to use it, and a key prerequisite. It could potentially note that the returned template is ready to paste directly, but the current text is sufficient for correct invocation and use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the single 'variant' parameter, including its enum values and default. The tool description does not add new semantic detail beyond implying multiple template types, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Return a guarded prompt template for a trading agent on Eterna.' It also enumerates key contents (risk caps, mandatory stop loss, approval gates), making the tool's function immediately identifiable and clearly distinct from the sibling tools, which cover connection status, fees, and setup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage context is provided: 'Use it as the system or session prompt once the Eterna tools are connected,' and the note 'No credentials needed' clarifies prerequisites. However, no explicit alternatives or exclusionary guidance are given, though none are strictly necessary given the clear differentiation from its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
eterna_compare_feesA
Compare monthly fees for the same volume and maker/taker mix across Eterna, Hyperliquid (base tier), Bybit (non-VIP) and Binance (regular user). Returns a table with sources. No credentials needed.
| Name | Required | Description | Default |
|---|---|---|---|
| maker_share | No | Fraction of volume executed as maker (0 to 1). | |
| monthly_volume_usd | Yes | Total monthly notional volume in USD. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It discloses that no credentials are needed, which is a meaningful auth/safety signal, and it specifies the return format as a table with sources. It does not describe data freshness or whether values are live, but the provided context is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences deliver the core purpose, the exact comparison scope, the output shape, and auth requirements with no filler. The most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple two-parameter comparison tool, the description covers purpose, input semantics, return format, and credential requirements. The main missing piece is explicit routing relative to the sibling eterna_fee_estimate, but the tool remains safely callable with the information provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both parameters with 100% coverage. The description adds value by clarifying that the comparison uses the 'same volume and maker/taker mix' across venues, which ties monthly_volume_usd and maker_share to the comparison semantics and reinforces the apple-to-apples nature of the tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Compare') with a concrete resource (monthly fees) and explicitly names the venues and tier basis being compared. This clearly distinguishes it from siblings like eterna_fee_estimate, which presumably focuses on a single exchange's fee estimate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when a user wants fee comparisons across Eterna, Hyperliquid, Bybit, and Binance for a given volume and maker/taker mix. However, it does not explicitly state when not to use it or mention alternatives such as eterna_fee_estimate for single-exchange fee estimation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
eterna_connection_statusA
Report whether this server is bridging the official Eterna MCP endpoint (token source, endpoint URL, number of remote tools exposed) and how to authenticate if it is not.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral disclosure burden. The verb 'report' strongly implies a read-only, side-effect-free operation, and the content is about querying status and returning instructions. However, it does not explicitly state that it performs no writes or makes no external calls, nor does it mention any potential delays or rate limits. It is adequate but not explicit about its non-destructive nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core purpose ('Report whether this server is bridging...') and then details the specifics. There is no redundant or filler language; every clause adds meaningful information about what the tool returns and when authentication guidance is given.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should fully clarify what the agent will receive. It mentions the items reported (token source, endpoint URL, number of remote tools) and the auth instructions, but it does not specify the response format (e.g., whether it returns a JSON object, a boolean, or a human-readable string). An agent calling this tool would not know how to parse the result. This is a meaningful gap for a status tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the description to explain about parameter semantics. Per the rubric, 0 parameters warrants a baseline score of 4. The description adds no parameter-related content, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: it reports whether the server bridges the official Eterna MCP endpoint, and specifies the details it provides (token source, endpoint URL, number of remote tools) plus authentication guidance if not bridged. This is a specific verb-resource pairing and distinctly differentiates from sibling tools like fee estimates or setup guides.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating what it reports, but it does not explicitly say when to use this tool versus alternatives, nor does it provide exclusions. For example, it doesn't state that this is the first step in troubleshooting or setup. The 'how to authenticate if it is not' clause hints at a use case, but it's not explicit enough for an agent to know when to invoke it over, say, eterna_setup_guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
eterna_fee_estimateA
Estimate monthly trading fees on Eterna Hybrid Exchange for a given notional volume and maker/taker mix, and the EHX credited back through EHX Payback. Uses the published flat schedule (0.014% maker / 0.035% taker). No credentials needed.
| Name | Required | Description | Default |
|---|---|---|---|
| maker_share | No | Fraction of volume executed as maker (0 to 1). Agents are usually taker-heavy; 0.3 is a common default. | |
| monthly_volume_usd | Yes | Total monthly notional volume in USD. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It reveals that the estimate is based on a published flat schedule (deterministic, not live-quoted), that no credentials are required (no auth), and that the result includes EHX Payback credits. It does not mention potential edge cases (e.g., fee changes) but covers the key behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the tool's purpose, and every clause earns its place: what it estimates, the key inputs, the fee schedule, the extra EHX Payback output, and the no-credentials note. No redundancy or padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool with no output schema, the description is nearly complete. An agent knows the required parameter, the optional parameter (with schema default), and the calculation basis. The only minor gap is the precise return shape (single figure vs. breakdown), but the mention of fees and EHX Payback implies a structured result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the base score is 3. The description adds value beyond the schema by specifying the actual fee rates (0.014% maker / 0.035% taker) and by clarifying that the maker/taker mix is the input, directly connecting the parameters to the calculation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Estimate') and resource ('monthly trading fees on Eterna Hybrid Exchange'), and adds distinctive details: EHX Payback credit and the flat fee schedule. This differentiates it from siblings like eterna_compare_fees, which presumably compares fee structs across venues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the use case: when a user wants fee projections for a given volume and maker/taker mix. It does not explicitly name alternatives or state when not to use it, but the context is unambiguous given the sibling set, and 'No credentials needed' provides a helpful practical cue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
eterna_setup_guideA
Step-by-step guide for connecting an AI agent to Eterna: the Claude connector (no code), the official CLI, a generic stdio MCP client via mcp-remote, or this starter server itself. No credentials needed.
| Name | Required | Description | Default |
|---|---|---|---|
| client | Yes | Which integration path to document. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It adds the useful note 'No credentials needed', implying no auth setup, but does not disclose what the tool returns (e.g., textual steps, a checklist) or whether it performs any action beyond presenting documentation. The description is not misleading, just minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the purpose, enumerates all options, and appends the key constraint ('No credentials needed') with no filler. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter guide tool with no output schema and no annotations, the description is nearly sufficient. It covers purpose, options, and the auth constraint. It could mention what the guide output looks like, but the tool is simple enough that this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes the 'client' parameter and its enum. The description adds value by explaining what each enum path means in plain language ('the Claude connector (no code), the official CLI, a generic stdio MCP client via mcp-remote, or this starter server itself'), helping the agent map values to real integration options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('connecting') and identifies the resource ('Eterna'), then enumerates exactly what integration paths the guide covers. It is clearly distinct from siblings like eterna_connection_status or eterna_fee_estimate, which address status and fees rather than setup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for setup/onboarding ('Step-by-step guide for connecting an AI agent to Eterna') and lists the four supported client types, which tells an agent when to call it. However, it does not explicitly contrast with siblings (e.g., 'use eterna_connection_status to verify a connection after setup'), so the guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v0.1.0- First observed
eterna_agent_prompt - First observed
eterna_compare_fees - First observed
eterna_connection_status - First observed
eterna_fee_estimate - First observed
eterna_setup_guide
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: connection status, fee estimation, fee comparison, setup guidance, and prompt generation. There is no overlap between them.
All tool names follow a consistent eterna_<purpose> pattern with snake_case. The only minor deviation is that some names are nouns (connection_status, setup_guide) while others are verbs (compare_fees), but the pattern is still predictable.
Five tools is a reasonable count for a starter/onboarding server. It is slightly thin compared to a full trading server, but each tool serves a distinct onboarding or informational purpose.
The server covers the stated purpose of onboarding and fee transparency well: status, setup, fee estimation, comparison, and agent prompt. A minor gap is the lack of a tool for actually executing trades or fetching live market data, but that appears to be out of scope for a starter server.
Maintenance
Related MCP Connectors
- FensoryOAuthcom.fensory
Non-custodial trading for AI agents: 1,900+ assets — US stocks, treasuries, gold, 250+ perps.
Non-custodial DeFi tools for AI agents on Solana: swaps, perps, lending, staking, equities.
Polymarket + Hyperliquid + macro for AI agents. 38 tools, signal backtest, SSE streaming. Free tier.
Non-custodial DeFi for AI agents: swaps, concentrated liquidity (V3/V4) zaps + ranges, 5 EVM chains
Related MCP Servers
- FlicenseAqualityCmaintenanceEnables AI agents to trade leveraged perpetual futures on Solana's Jupiter Perpetuals while providing tools for market data and technical analysis. It supports portfolio management, fee estimation, and automated position execution for SOL, ETH, and BTC using USDC collateral.132-
- FlicenseNot gradedqualityFmaintenanceAI-native cryptocurrency exchange built for autonomous agents. Register, deposit USDC, select a strategy, and trade 8 crypto pairs (BTC, ETH, SOL + more) programmatically — no KYC required. Includes sandbox with 10,000 virtual USDC for testing.-

Purple Flea Tradingofficial
AlicenseNot gradedqualityDmaintenancePerpetual futures trading API for AI agents. Access 275+ markets (crypto, stocks, commodities, forex) via Hyperliquid. Copy trading, leaderboard, up to 50x leverage. No KYC. 20% referral commissions.29 npmMIT
Eterna MCPofficial
AlicenseNot gradedqualityBmaintenancePremium low cost execution layer for AI trading agents, with access to perpetual futures trading across 500+ pairs and $10B+ in aggregated liquidity.8MIT