ARES MCP

ARES MCP is the read-only, verification-first MCP surface for ARES Protocol.

It wraps the public ARES API without changing payload meaning. Indexed reads, local/demo reads, and direct-chain fallback semantics stay intact because the MCP server delegates to the same public API truth used by the explorer and SDKs.

What it exposes

• health
• get_agent
• get_score
• get_actions
• get_disputes

5-minute quickstart

1. Install the published packages

npm install @aresprotocol/sdk

Run the published MCP server with npx:

ARES_API_BASE=https://ares-protocol.xyz/api npx -y @aresprotocol/mcp

If you only need the MCP server, @aresprotocol/sdk is optional. If you want both a direct SDK client and the MCP surface in one project:

npm install @aresprotocol/sdk @aresprotocol/mcp

If ARES_API_BASE is omitted, the default is:

https://ares-protocol.xyz/api

2. Local repository development path

If you are working inside this monorepo and want the local workspace build instead of the published package:

npm ci
npm run mcp:build
ARES_API_BASE=https://ares-protocol.xyz/api node mcp/ares-mcp/dist/index.js

Example MCP client config

{
  "mcpServers": {
    "ares": {
      "command": "node",
      "args": ["mcp/ares-mcp/dist/index.js"],
      "env": {
        "ARES_API_BASE": "https://ares-protocol.xyz/api"
      }
    }
  }
}

Ready-to-use config variants:

• mcp/ares-mcp/config/claude-desktop.json
• mcp/ares-mcp/config/cursor.json
• mcp/ares-mcp/config/windsurf.json
• mcp/ares-mcp/config/codex.json

Copy-paste install matrix

SDK only

npm install @aresprotocol/sdk

MCP only

npx -y @aresprotocol/mcp

SDK + MCP in one project

npm install @aresprotocol/sdk @aresprotocol/mcp
ARES_API_BASE=https://ares-protocol.xyz/api npx -y @aresprotocol/mcp

Example tool flows

Health

Tool:

{
  "name": "health",
  "arguments": {}
}

Agent lookup

Tool:

{
  "name": "get_agent",
  "arguments": {
    "address": "star"
  }
}

Equivalent curl:

curl https://ares-protocol.xyz/api/v1/agent/star

Equivalent TypeScript:

import { AresClient } from '@aresprotocol/sdk';

const client = new AresClient({ apiBase: 'https://ares-protocol.xyz/api' });
const agent = await client.getAgent('star');

Equivalent Python:

from ares_sdk import AresClient

client = AresClient("https://ares-protocol.xyz/api")
agent = client.get_agent("star")

Score lookup

Tool:

{
  "name": "get_score",
  "arguments": {
    "address": "star"
  }
}

Equivalent curl:

curl https://ares-protocol.xyz/api/v1/score/star

Actions

Tool:

{
  "name": "get_actions",
  "arguments": {
    "agent": "star",
    "limit": 5
  }
}

Equivalent curl:

curl "https://ares-protocol.xyz/api/v1/actions?agent=star&limit=5"

Equivalent TypeScript:

const actions = await client.getActions({ agent: 'star', limit: 5 });

Equivalent Python:

actions = client.get_actions(agent="star", limit=5)

Disputes

Tool:

{
  "name": "get_disputes",
  "arguments": {
    "agent": "star",
    "limit": 5
  }
}

Equivalent curl:

curl "https://ares-protocol.xyz/api/v1/disputes?agent=star&limit=5"

Equivalent TypeScript:

const disputes = await client.getDisputes({ agent: 'star', limit: 5 });

Equivalent Python:

disputes = client.get_disputes(agent="star", limit=5)

Response contract

Each MCP tool returns a stable envelope:

{
  "tool": "get_agent",
  "apiBase": "https://ares-protocol.xyz/api",
  "endpoint": "/v1/agent/star",
  "fetchedAt": "2026-04-20T12:00:00.000Z",
  "data": {}
}

data preserves the upstream ARES API response shape. The MCP layer does not rename fields or flatten visibility semantics.

Truth boundaries

• Registration and visibility are not the same thing.
• Newly registered agents may resolve through indexed data or direct-chain fallback.
• Live scoring enablement remains approval-based.
• ares-mcp v1 is read-only and does not write to chain or API state.
• Canonical demo sequence for ARES now lives in demo-arc.md.

Release validation

npm run mcp:test
npm run mcp:smoke
npm run mcp:pack