agents-mcp-server

A monorepo of focused MCP (Model Context Protocol) servers that give an AI agent safe, composable access to web3 market data and trading — split by concern so that reading the chain and acting on it are never the same surface.

• Read-only intelligence & data servers expose on-chain analytics and market data. They never sign or send anything.
• Execution servers place trades and swaps, and gate every action behind an explicit SIM | PAPER | LIVE mode so an agent can never accidentally move funds.
• A tiny shared framework (@agentsmcp/mcp-core) makes every server a flat registry of tool modules — adding a tool is one file, not a new switch arm.

Built with TypeScript (strict, ESM, Node ≥22), the MCP SDK, Zod, and Vitest; formatted/linted with Biome; secrets encrypted at rest with dotenvx.

---

Architecture

flowchart TB
  agent["AI agent / MCP client"]

  subgraph readonly["Read-only servers (no signing)"]
    intel["web3-intel<br/>9 tools · wallet & token intelligence"]
    market["web3-market-data<br/>15 tools · multi-venue market data"]
  end

  subgraph exec["Execution servers (SIM · PAPER · LIVE)"]
    hl["web3-hyperliquid-trading<br/>4 tools · perps"]
    onchain["web3-onchain-trading<br/>6 tools · 0x + Jupiter swaps"]
  end

  subgraph core["Shared packages"]
    mcpcore["@agentsmcp/mcp-core<br/>tool registry · stdio runtime · CLI"]
    providers["web3-core-onchain<br/>Alchemy · Helius · 0x · Jupiter · Codex"]
    wallets["web3-core-wallets<br/>encrypted wallet resolution"]
    norm["web3-core-hyperliquid<br/>position/account normalization"]
  end

  ext["External APIs<br/>Alchemy · Helius · Codex · Hyperliquid · 0x · Jupiter"]

  agent -- stdio/JSON-RPC --> intel & market & hl & onchain
  intel & market & hl & onchain --> mcpcore
  intel & market & onchain --> providers
  hl & onchain --> wallets
  market --> norm
  providers --> ext
  hl --> ext

Server	Kind	Tools	Talks to
web3-intel	read-only	9	Alchemy, Helius, Codex
web3-market-data	read-only	15	Hyperliquid, Alchemy, Helius
web3-hyperliquid-trading	execution	4	Hyperliquid
web3-onchain-trading	execution	6	0x (EVM), Jupiter (Solana)

Shared packages: @agentsmcp/mcp-core · web3-core-onchain · web3-core-wallets · web3-core-hyperliquid · mcp-test-harness.

The tool-registry pattern

Every server is just a list of ToolDefinitions wired through mcp-core. There is no per-server switch, no repeated server bootstrap, and no duplicated CLI.

// web3-onchain-trading/src/tools/zerox.ts
import { type ToolDefinition, jsonText } from '@agentsmcp/mcp-core';

export const getQuote0x: ToolDefinition = {
  name: 'get_quote_0x',
  description: 'Get a 0x swap quote for an EVM trade…',
  inputSchema: zeroXQuoteInputJsonSchema,
  annotations: { readOnlyHint: true },
  async handler(rawArgs, deps) {
    const { args, quote, fee } = await fetch0xQuote(rawArgs, deps); // deps.fetch is injectable
    return jsonText({ provider: '0x', ...args, fee, quote });
  },
};

// web3-onchain-trading/src/index.ts — the whole server
import { createToolRouter } from '@agentsmcp/mcp-core';
import { tools } from './tools/index.js';

export function createOnchainTradingRouter(deps?) {
  return createToolRouter(tools, { serverName: 'web3-onchain-trading', deps });
}

createToolRouter dispatches by name via a Map and wraps every failure as "<server> <tool> failed: …". runStdioServer and runCli (in cli.ts) provide the SDK server and the dotenvx bootstrap. Adding a tool = write one tools/*.ts module and add it to the tools array.

The injectable deps.fetch is the testing seam: handlers are unit-tested by passing a mock fetch, with no network and no live keys (see any *.mock.test.ts).

Execution safety: SIM · PAPER · LIVE

Every execution tool requires a mode:

• SIM / PAPER — never touch the network and never resolve wallet secrets; they return exactly what would be sent. Safe for an agent to call freely.
• LIVE — the only mode that signs and broadcasts. It resolves the selected wallet on demand and (for Hyperliquid) verifies the account matches the wallet.

Wallet private keys are never stored in code or JSON. A wallet file holds metadata plus pointers to env vars; the actual secrets live in an dotenvx-encrypted ~/.agentsmcp/.env.

Quickstart

pnpm install
pnpm build                 # build all packages
pnpm test                  # unit + mock + contract tests (e2e auto-skip)
pnpm check                 # Biome + MCP registry validation

# configure secrets / wallet (see .env.example for every variable)
pnpm wallet add main       # create an encrypted wallet
pnpm env:set ALCHEMY_API_KEY <key>

Run a server over stdio (e.g. with the MCP Inspector):

pnpm --filter @agentsmcp/web3-intel inspect

Point an MCP client at the server's dist/cli.js (each package ships a bin).

Testing

pnpm test                  # all workspaces, sequential + visible output
pnpm test:coverage         # with V8 coverage report
RUN_E2E=1 pnpm test        # also run live-API e2e tests (needs real keys)

Tests are layered: contract tests spawn the built server over stdio and assert its tool list; mock tests exercise handlers with an injected fetch; e2e tests hit real APIs and are gated behind RUN_E2E=1 so a normal run is fast and offline.

Repository layout

packages/
  mcp-core/             # tool registry + stdio runtime + CLI bootstrap (the framework)
  web3-core-onchain/    # Alchemy/Helius/0x/Jupiter/Codex providers + request builders
  web3-core-wallets/    # wallet metadata + encrypted secret resolution
  web3-core-hyperliquid/# Hyperliquid position/account normalization
  mcp-test-harness/     # McpStdioClient used by contract/e2e tests
web3-intel/             # read-only intelligence server
web3-market-data/       # read-only market-data server
web3-hyperliquid-trading/  # perps execution server
web3-onchain-trading/   # spot-swap execution server
web/docs/               # Astro/Starlight documentation site
scripts/                # wallet CLI, registry validation, publish

See ARCHITECTURE.md for a deeper tour, and .env.example for every environment variable.

License

MIT