🔌 MCP Server v2.0

MCP Server

TrustGrade ships as a Model Context Protocol (MCP) server with 7 tools that let AI agents verify trust before executing crypto transactions. Install once, works with any MCP-compatible client.

Installation

bash Install

# Using npx (recommended — no install needed)
npx @trustgrade/mcp-server

# Or install globally
npm install -g @trustgrade/mcp-server

# Verify installation
trustgrade-mcp --version
# → 2.0.0

Environment Variables

Variable	Required	Default	Description
`TRUSTGRADE_API`	No	`https://api.trustgrade.ai`	API base URL
`TRUSTGRADE_API_KEY`	Yes	—	Your TrustGrade API key

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or equivalent:

json claude_desktop_config.json

{
  "mcpServers": {
    "trustgrade": {
      "command": "npx",
      "args": ["-y", "@trustgrade/mcp-server"],
      "env": {
        "TRUSTGRADE_API": "https://api.trustgrade.ai",
        "TRUSTGRADE_API_KEY": "tg_live_xxx"
      }
    }
  }
}

Cursor

Create .cursor/mcp.json in your project root:

json .cursor/mcp.json

// .cursor/mcp.json
{
  "mcpServers": {
    "trustgrade": {
      "command": "npx",
      "args": ["-y", "@trustgrade/mcp-server"],
      "env": {
        "TRUSTGRADE_API": "https://api.trustgrade.ai",
        "TRUSTGRADE_API_KEY": "tg_live_xxx"
      }
    }
  }
}

Any MCP Client

TrustGrade uses standard stdio transport. Any MCP-compatible client can connect:

bash stdio transport

# Stdio transport — runs as subprocess
npx @trustgrade/mcp-server

# The server reads TRUSTGRADE_API_KEY from environment
# and communicates via JSON-RPC over stdin/stdout

How Agents Use TrustGrade

text Agent Decision Flow

User gives task
       │
       ▼
  ┌─────────┐
  │  Agent   │
  └────┬─────┘
       │ "Swap 1000 USDC on Uniswap"
       ▼
  ┌─────────────────────┐
  │ check_trust         │ ← MCP tool
  │ ("defi_protocol",   │
  │  "Uniswap")          │
  └────────┬────────────┘
           │
     Score ≥ 80? ────── NO ──→ 🚫 ABORT
           │                        │
          YES                  Log reason
           │                  Notify user
           ▼
  ┌─────────────────────┐
  │ Execute transaction │
  └─────────────────────┘
           │
           ▼
      ✅ Done

check_trust

Score any entity — the primary tool. Always call before recommending or executing transactions with an entity.

Parameter	Type	Required	Description
`entityType`	string	Yes	Entity type (e.g. `defi_protocol`, `stablecoin`)
`entityId`	string	Yes	Entity name or address

json Example

// Agent calls check_trust before recommending a DeFi protocol
{
  "name": "check_trust",
  "arguments": {
    "entityType": "defi_protocol",
    "entityId": "Uniswap"
  }
}

// MCP response:
✅ TrustGrade: Score 100/100 (Grade: A+) | Confidence: 88% | 🟢 LOW RISK
Exceptional trust profile for this defi protocol. TVL Stability (30-day) above average. Audit Coverage above average.

When to use: Before any agent interaction with a DeFi protocol, stablecoin, or smart contract.

verify_agent

Verify AI agent identity — checks agent DID, business KYB status, trust score, and active status.

Parameter	Type	Required	Description
`agentDID`	string	Yes	Agent DID (`did:trustgrade:domain:agentId`)

json Example

// Verify an AI agent before accepting its transaction
{
  "name": "verify_agent",
  "arguments": {
    "agentDID": "did:trustgrade:shop.example.com:agent-001"
  }
}

// MCP response:
✅ VERIFIED
Agent: did:trustgrade:shop.example.com:agent-001
Business: 0x742d...44C7
Model: gpt-5.5
Trust Score: 92
Reason: All checks passed

When to use: When your agent receives a request from another agent. Verify identity before trusting instructions.

verify_transaction

Verify a transaction BEFORE executing — the core safety tool. Checks agent limits, business verification, trust score, recipient whitelist, and manipulation flags. Returns a cryptographic receipt.

Parameter	Type	Required	Description
`agentDID`	string	Yes	Agent DID to verify
`to`	string	Yes	Recipient address
`amount`	number	Yes	Transaction amount in USD
`memo`	string	No	Optional transaction memo

json Example

// Verify a transaction BEFORE letting the agent execute it
{
  "name": "verify_transaction",
  "arguments": {
    "agentDID": "did:trustgrade:shop.example.com:agent-001",
    "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f6E44",
    "amount": 500,
    "memo": "Supplier payment"
  }
}

// MCP response:
✅ APPROVED
Agent: did:trustgrade:shop.example.com:agent-001
Score: 92
Timestamp: 2026-07-12T10:55:00Z
Receipt Hash: 0x3a8f...c1b9
Signature: 0x9f2e...8a4d...

// If rejected:
🚫 BLOCKED
Agent: did:trustgrade:shop.example.com:agent-001
Reason: Amount exceeds agent daily limit ($10,000)

⚠️ Critical: Always verify_transaction before letting agents execute. Block the transaction if the result is rejected.

get_business

Business verification status — KYB level, domain verification, agent count, and trust score.

Parameter	Type	Required	Description
`walletAddress`	string	Yes	Business admin wallet address (0x...)

json Example

{
  "name": "get_business",
  "arguments": {
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f6E44"
  }
}

// Response:
{
  "business": "Acme Commerce Ltd",
  "kyb_level": 2,
  "kyb_status": "enhanced",
  "domain_verified": true,
  "agent_count": 3,
  "trust_score": 88,
  "registered_at": "2026-06-15T12:00:00Z"
}

When to use: Due diligence on businesses before accepting agent payments or establishing agent commerce relationships.

register_agent

Register a new AI agent — requires business to be KYB-verified. Returns agent DID, public key, and onchain registration status.

Parameter	Type	Required	Description
`adminWallet`	string	Yes	Business admin wallet
`agentName`	string	Yes	Display name for the agent
`model`	string	Yes	AI model (e.g. `gpt-5.5`, `claude-4.5`)
`capabilities`	string[]	No	Agent capabilities (e.g. `["payments", "refunds"]`)
`maxTxValue`	number	No	Max single transaction USD (default: 1000)
`dailyLimit`	number	No	Daily spending limit USD (default: 10000)

json Example

{
  "name": "register_agent",
  "arguments": {
    "adminWallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f6E44",
    "agentName": "Acme Checkout Agent",
    "model": "gpt-5.5",
    "capabilities": ["payments", "refunds", "balance_check"],
    "maxTxValue": 1000,
    "dailyLimit": 10000
  }
}

// Response:
{
  "did": "did:trustgrade:acme.com:agent-004",
  "publicKey": "0x4f8a...e2b1",
  "status": "active",
  "maxTxValue": 1000,
  "dailyLimit": 10000,
  "registered_at": "2026-07-12T10:55:00Z"
}

When to use: Onboarding new agents. One-time call per agent.

list_entity_types

List all supported entity types for trust scoring. No parameters required.

json Example

{
  "name": "list_entity_types",
  "arguments": {}
}

// Response:
[
  { "type": "defi_protocol", "name": "DeFi Protocol" },
  { "type": "stablecoin", "name": "Stablecoin" },
  { "type": "ai_agent", "name": "AI Agent" },
  { "type": "smart_contract", "name": "Smart Contract" },
  { "type": "token", "name": "Token" },
  { "type": "nft_collection", "name": "NFT Collection" },
  { "type": "dao", "name": "DAO" }
]

compare_trust

Compare trust scores across multiple entities side-by-side.

Parameter	Type	Required	Description
`entities`	array	Yes	Array of `{ type, id }` objects to compare

json Example

{
  "name": "compare_trust",
  "arguments": {
    "entities": [
      { "type": "stablecoin", "id": "USDC" },
      { "type": "stablecoin", "id": "USDT" },
      { "type": "stablecoin", "id": "DAI" }
    ]
  }
}

// Response:
┌─────────┬───────┬───────┬────────────┐
│ Entity  │ Grade │ Score │ Confidence │
├─────────┼───────┼───────┼────────────┤
│ USDC    │ B-    │ 82    │ 79.1%      │
│ USDT    │ C+    │ 75    │ 79.1%      │
│ DAI     │ F     │ 48    │ 79.1%      │
└─────────┴───────┴───────┴────────────┘

Recommendation: USDC has the highest trust score.

When to use: When an agent needs to choose between multiple protocols or stablecoins for a transaction.

Agent Integration Patterns

🔒 Pre-Transaction Check

Call check_trust before every transaction. Abort if score < threshold (typically 65 or 80).

python

# Pseudocode
score = check_trust(type, entity)
if score < AGENT_THRESHOLD:
    abort(f"TrustGrade: {score.grade} too low")
else:
    execute()

📊 Portfolio Scanning

Scan all entities in a user's portfolio. Alert on any that drop below threshold.

python

for position in portfolio:
    score = check_trust(position.type, position.entity)
    if score.score < 65:
        alert(f"{position.entity} dropped to {score.grade}")

🔍 Listing Due Diligence

Before listing a new token or protocol on your platform, require a minimum TrustGrade score.

python

score = check_trust(token.type, token.id)
if score.grade in ['A+', 'A', 'A-', 'B+', 'B', 'B-']:
    approve_listing(token)
else:
    request_manual_review(token)