Abstraxn Agent Layer

Abstraxn 公共 Web3 MCP 服务

面向 Web3 数据的免费公共 MCP（Model Context Protocol）服务。将任意 MCP 客户端（Claude Desktop、Cursor 或你自己的 Agent）连接到此服务，即可读取实时链上数据（区块高度、gas、交易状态、ERC-20 信息、现货价格）、查询天气预报、构建未签名的 EVM/Solana 转账交易；此外，少数按次付费的工具还可查询市场数据、钱包/代币/ENS、旅行搜索、地点/太阳能/航拍视图数据，以及社交资料身份信息。

无需 API 密钥、无需账户、无需注册。 免费工具人人可用；付费工具通过 x402 支付协议直接从调用者自己的钱包结算——此服务绝不会代替你持有或签署资金。

基于官方 @modelcontextprotocol/sdk 和 NestJS 11 构建。

目录

• 快速开始
• 通过 Claude Desktop / Cursor 使用
• 可用工具
• 直接调用工具（curl）
• 配置
• 工作原理
• 数据库
• 安全性
• 脚本
• 参与贡献

---

快速开始

git clone https://github.com/Abstraxn-Labs/abstraxn-agent-layer.git
cd abstraxn-agent-layer
npm install
cp .env.example .env
# Edit .env: Postgres connection + UPSTREAM_RELAY_BASE_URL / ENRICHMENT_RELAY_BASE_URL
# (each required for its own group of paid tools) + WEATHERAPI_KEY (required for weather.forecast)
npm run start:dev

• 健康检查：GET http://localhost:3011/health
• MCP 端点：POST http://localhost:3011/mcp
• API 文档（仅健康检查）：http://localhost:3011/api/docs

数据库迁移会在启动时自动运行——无需单独执行 CLI 步骤。

通过 Claude Desktop / Cursor 使用

将以下内容添加到 MCP 客户端的配置中（例如 claude_desktop_config.json 或 Cursor 的 mcp.json）：

{
  "mcpServers": {
    "abstraxn-public-web3": {
      "url": "http://localhost:3011/mcp"
    }
  }
}

重启客户端后，下方的工具即可使用——无需进行其他设置。

可用工具

工具	付费？	功能
network.blocknumber	否	查询当前 EVM 区块编号或 Solana 槽位。可查询单条链，也可一次查询全部。
network.transaction_status	否	根据哈希查询 EVM 或 Solana 上的交易/签名。
network.gas_info	否	查询 EVM 链的当前 gas 价格及 EIP-1559 费用提示。
network.token_info	否	查询 ERC-20 名称 / 符号 / 小数位数 / 总供应量。
network.token_price	否	通过 CoinGecko 查询现货价格（默认为 ETH/USD）。
network.prepare_transfer	否	根据明确指定的 from/to/amount 构建未签名的原生代币/ERC-20/SPL 转账交易。绝不签名或广播。
weather.forecast	否	查询当前天气状况、天气预报、天文信息、地点搜索、历史天气和海洋天气，共 6 项操作。
market.crypto	是	查询加密货币市场数据（来源于 CoinGecko），共 6 项操作。
web3.lookup	是	多链钱包 / 代币 / ENS / 交易模拟查询，共 7 项操作。
travel.search	是	搜索航班和酒店，共 2 项操作。
places.lookup	是	查询地点 / 太阳能 / 航拍视图，共 11 项操作。
social.profile_lookup	是	对一批记录进行个人 / 社交资料身份解析。

工具按领域命名（network.*、market.*、web3.*、travel.*、places.*、 social.*），MCP 客户端可按树状结构浏览，而不是查看扁平列表。

付费工具的工作方式： 无需支付即可调用工具，此时会收到 paymentRequired 挑战（而非错误）。钱包客户端会为其签名，并在重试相同调用时设置 paymentPayload——费用由你的钱包直接支付；此服务仅负责转发请求。

直接调用工具（curl）

大多数人会使用 MCP 客户端（见上文），但如果你想直接通过脚本调用，此端点也提供基于 HTTP 的纯 JSON-RPC：

BASE=http://localhost:3011
ACCEPT='Accept: application/json, text/event-stream'   # required by the MCP spec

# 1. Initialize a session
curl -s -X POST "$BASE/mcp" -H 'Content-Type: application/json' -H "$ACCEPT" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}'

# 2. List available tools
curl -s -X POST "$BASE/mcp" -H 'Content-Type: application/json' -H "$ACCEPT" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Call a tool
curl -s -X POST "$BASE/mcp" -H 'Content-Type: application/json' -H "$ACCEPT" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"network.token_price","arguments":{"symbol":"bitcoin"}}}'

GET /mcp 会按设计返回 405——每次调用都是无状态的，因此没有可恢复的会话。

配置

将 .env.example 复制为 .env。除标记为必填的项外，所有配置均有安全默认值：

变量	必填	说明
PORT	否	HTTP 端口（默认 3011）
POSTGRES_HOST / PORT / USER / PASSWORD / DB	否	Postgres 连接配置，仅用于滥用追踪
PUBLIC_MCP_RATE_LIMIT_PER_MIN / _WINDOW_MS	否	全局 IP 速率限制（默认每分钟 30 次）
CHAIN_RPC_*	否	各链的 EVM RPC 覆盖配置 — 未设置时使用公共默认值（见 src/mcp/utils/chain-registry.util.ts）
SOLANA_RPC_URL / SOLANA_DEVNET_RPC_URL	否	Solana 集群 RPC 覆盖配置
WEATHERAPI_KEY	是	weather.forecast 的免费 API 密钥 — 可在 WeatherAPI.com 的注册页面获取（免费套餐每月提供 100K 次调用，不使用任何付费功能）。未设置时，weather.forecast 会返回明确错误，而不会导致整个服务失败。
WEATHERAPI_BASE_URL	是	weather.forecast 的上游基础 URL — 源代码中没有提交默认值，因此在设置前，该工具会正常报错（.env.example 中提供 https://api.weatherapi.com/v1；可覆盖此值，以便在本地测试时指向模拟服务或自托管镜像）。
UPSTREAM_RELAY_BASE_URL	是	market.crypto / web3.lookup / travel.search 背后的上游中继基础 URL — 未提交默认值，因此在设置前，这 3 个工具都无法使用
ENRICHMENT_RELAY_BASE_URL	是	places.lookup / social.profile_lookup 背后的上游中继基础 URL — 与 UPSTREAM_RELAY_BASE_URL 指向不同的上游，未提交默认值

工作原理

MCP client (Claude Desktop, Cursor, your agent)
    → POST /mcp  (this service, stateless — a fresh McpServer per request)
    → free tools: direct chain RPC / CoinGecko calls
    → paid tools: relayed upstream, settled by the caller's wallet via x402

这是一个独立部署的单体服务 — 它与任何其他 Abstraxn 服务都不共用工作区或数据库。这是有意为之：一些 MCP 注册目录要求公共 MCP 服务位于自己的仓库中，只有一个路由和一组固定工具，并且可以端到端审查。

技术栈： Node.js 20+ · NestJS 11 · @modelcontextprotocol/sdk ^1.30.0（官方 SDK）· PostgreSQL + TypeORM · @x402/core · viem（EVM）+ 原始 JSON-RPC（Solana 读取）· @solana/web3.js + @solana/spl-token（Solana 转账构建）· @skalenetwork/bite（SKALE 隐私加密转账）· helmet、 @nestjs/throttler

数据库

Postgres 仅用于滥用追踪 — 不存在租户、策略或配置表：

表	用途
observed_ips	每个调用方 IP 对应一行，记录累计调用次数和最后访问时间。
observed_wallets	每个通过 x402 付款的钱包地址对应一行。
public_mcp_transactions	已完成付费调用的仅追加历史记录。

如果无法连接 Postgres，调用仍会成功 — 追踪写入采用尽力而为的方式，绝不会阻塞或导致真实 MCP 请求失败。

安全

由于任何人都可以不使用密钥调用此服务，有几项重要约束：

• 不存在 SSRF 攻击面： 每个出站 URL（链 RPC、上游中继、CoinGecko）都来自服务端配置 — 没有工具会接受调用方提供的 URL。
• 速率限制是全局的，并以 IP 为键 — 在没有账户的情况下，这是唯一可用的调控手段。如果服务部署在反向代理之后，请在 main.ts 中设置 app.set('trust proxy', ...)，否则限流器会限制代理，而不是真实调用方。
• 除数据库密码和 WEATHERAPI_KEY 外，不存在其他密钥，二者仅通过环境变量配置，且绝不会记录到日志中 — weather.forecast 会将密钥作为查询参数构建其提供商请求 URL，但所有日志行只会包含操作名称和错误消息，绝不包含 URL 本身。
• CORS 有意设为通配符 — 此处不会有任何租户专属内容跨越来源边界。

发现安全问题？请先阅读 CONTRIBUTING.md，再提交公开问题。

脚本

脚本	描述
npm run start:dev	以监听模式运行
npm run build	编译到 dist/
npm run start:prod	运行编译后的构建（dist/main）
npm run lint	ESLint
npm test	Jest — 单元测试、SDK 级集成测试和 HTTP 冒烟测试

贡献

欢迎提交问题和 PR — 如何添加新工具以及项目的完成标准，请参阅 CONTRIBUTING.md。

许可证：MIT