@clearagent/mcp

Model Context Protocol (MCP) server for ClearAgent API — exposes OFAC/BSA compliance screening and AI agent credentials management as tools for Claude Desktop, Cursor, and other MCP-compatible clients.

ClearAgent is a pre-settlement compliance API that screens AI agent payments against OFAC sanctions, enforces spend policies, and returns a verdict (CLEAR/REVIEW/BLOCKED) in under 50ms — before settlement. This MCP server lets any LLM client call the full ClearAgent API surface as native tools.

Features

• Health Check — API status and OFAC list statistics
• Operator Registration — onboard new organizations
• Agent Credentials — issue and manage KYA agent tokens
• User Management — register compliance officers and BSA officers
• Fleet Management — create spend envelopes for multi-agent operations
• Agent Delegation — mint child agent credentials with refined policies
• Core Screening — screen transactions against OFAC, spend policies, and BSA rules
• Demo Screening — public sandbox for testing (no auth required)
• Review/Disposition — BSA officer approval/rejection/SAR escalation
• Audit Trails — retrieve screening records and metadata
• Billing & Usage — check monthly usage, limits, and plan status
• Alerts — daily OFAC re-screening alerts

Installation

npm install @clearagent/mcp

Quick Start

1. Configure Environment

Set your ClearAgent credentials:

export CLEARAGENT_API_KEY="your_operator_jwt_here"
export CLEARAGENT_AGENT_TOKEN="your_agent_jwt_here"

The CLEARAGENT_API_KEY (KYAOperatorCredential) is required for authenticated endpoints. The CLEARAGENT_AGENT_TOKEN (KYAAgentCredential) is used by the clearagent_screen tool and can be overridden per request.

2. Claude Desktop Configuration

Add the MCP server to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "clearagent": {
      "command": "npx",
      "args": ["@clearagent/mcp"],
      "env": {
        "CLEARAGENT_API_KEY": "your_operator_jwt",
        "CLEARAGENT_AGENT_TOKEN": "your_agent_jwt"
      }
    }
  }
}

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

3. Start Claude Desktop

Claude now has access to all ClearAgent tools. Ask Claude to screen transactions, manage agents, or check usage:

• "Screen a transaction with wallet 0x1234... on Ethereum for $500"
• "Check my monthly API usage and limits"
• "List any recent OFAC re-screening alerts"

Tools Reference

Health & Status

clearagent_health

Returns API version and OFAC list statistics. No authentication required.

Input: None

Output: API version, SDN entity count, wallet address counts by chain.

Operator & User Management

clearagent_register_operator

Register a new ClearAgent operator. Issues both a KYAOperatorCredential (1-year Bearer token) and an initial KYAAgentCredential (90-day agent token).

Input:

• legalName (string, required) — Company legal name
• email (string, required) — Operator email
• wallet (string, optional) — Wallet address for on-chain verification
• description (string, optional) — Company description
• plan (enum: "starter" | "pro", optional) — Billing plan

Output: Operator ID, operator token, agent token, plan details.

Rate limit: 3 per email per day

clearagent_register_user

Register an authorized user (compliance officer, BSA officer, admin) under the operator.

Input:

• operatorToken (string, required) — Operator JWT
• userLegalName (string, required) — User name
• userRole (string, optional) — Role (e.g., "bsa_officer", "compliance_officer")
• userWallet (string, optional) — Wallet address
• txLimit (number, optional) — Transaction approval limit in USDC

Output: User ID, role, permissions.

Agent Credentials

clearagent_register_agent

Register an additional AI agent under the operator. Issues a new KYAAgentCredential.

Input:

• agentName (string, required) — Display name
• operatorWallet (string, required) — Operator wallet
• agentFramework (string, optional) — Framework (e.g., "Claude", "ReAct")
• underlyingModel (string, optional) — Model (e.g., "gpt-4", "claude-opus")
• operatorLegalName (string, optional) — Company name
• purpose (string, optional) — Use case description
• mode (enum: "supervised" | "autonomous", optional) — Operation mode
• spendPolicy (object, optional) — Spend limits:
  • maxSingleTxUSDC (number) — Per-transaction limit
  • dailyLimitUSDC (number) — Daily limit
  • allowedChains (array of strings) — Allowed blockchains

Output: Agent ID, agent token (JWT), spend policy.

clearagent_attest_agent

Human heartbeat re-attestation. A user confirms the agent is still authorized and healthy.

Input:

• agentId (string, required) — Agent ID
• userToken (string, required) — User JWT

Output: Attestation timestamp, new validity window.

clearagent_create_delegate

Mint a child agent credential from a parent agent. The child inherits or refines the parent's policy.

Input:

• parentToken (string, required) — Parent agent JWT
• childName (string, required) — Child display name
• childPurpose (string, optional) — Child use case
• childSpendPolicy (object, optional) — Spend limits for child

Output: Child agent ID, child agent token.

Fleet Management

clearagent_create_fleet

Create a fleet spend envelope — a container for multiple agents with shared limits.

Input:

• operatorToken (string, required) — Operator JWT
• fleetName (string, required) — Fleet name
• spendEnvelope (object, optional) — Fleet-wide limits:
  • maxSingleTxUSDC (number)
  • dailyLimitUSDC (number)

Output: Fleet ID, spend envelope.

Screening

clearagent_screen

Core endpoint. Screen a transaction against OFAC sanctions, spend policies, and BSA rules. Verdict is CLEAR, REVIEW, BLOCKED, or UNKNOWN.

Input:

• token (string, optional) — Agent JWT (defaults to CLEARAGENT_AGENT_TOKEN)
• amount (number, optional) — Amount in USDC
• chain (string, optional) — Blockchain name
• cpWallet (string, optional) — Counterparty wallet address
• cpName (string, optional) — Counterparty name
• protocol (string, optional) — Protocol (e.g., "MPP", "x402")
• rail (string, optional) — Payment rail (e.g., "Stripe", "Coinbase")
• cpType (string, optional) — Type (e.g., "merchant", "exchange")

Output:

• verdict — One of: CLEAR, REVIEW, BLOCKED, UNKNOWN
• txnId — Transaction ID (for audit trail)
• agentId — Screened agent
• ruleTriggered — Rule that triggered verdict (if applicable)
• reason — Human-readable explanation
• riskScore — Numeric risk (0-100)
• screenedAt — ISO timestamp
• responseTimeMs — Response latency

Verdict meanings:

• CLEAR — Counterparty passed all checks. Safe to settle.
• REVIEW — Soft flag (e.g., spend policy near limit, velocity spike). Awaiting human disposition.
• BLOCKED — Hard block (e.g., OFAC hit, credential revoked). Payment must not settle.
• UNKNOWN — Insufficient data (credential missing or expired).

Auth: Requires CLEARAGENT_API_KEY in Authorization header.

clearagent_demo_screen

Public demo screening with canned scenarios. No authentication required.

Input:

• scenario (number, optional) — Scenario ID (1-5):

  1. All clear — Passes all checks
  2. OFAC name hit — Counterparty on SDN list
  3. Wallet hit — Wallet address sanctioned
  4. Spend policy violation — Exceeds daily limit
  5. Model change — Velocity spike / unusual hours

• cpName (string, optional) — Override counterparty name

• cpWallet (string, optional) — Override wallet

Output: Same as clearagent_screen.

Rate limit: 30 per IP per hour.

Auth: None (public endpoint).

Review & Audit

clearagent_review

BSA officer disposition on a REVIEW screening verdict. Records the human decision in the audit trail.

Input:

• txnId (string, required) — Transaction ID
• disposition (enum: "APPROVED" | "REJECTED" | "ESCALATE_SAR", required)
  • APPROVED — Allow payment to settle
  • REJECTED — Block payment
  • ESCALATE_SAR — File Suspicious Activity Report
• reviewedBy (string, required) — Reviewing officer name/ID
• notes (string, optional) — Review justification

Output: Disposition timestamp, audit record.

Auth: Requires CLEARAGENT_API_KEY. Only users with role bsa_officer, compliance_officer, or admin can submit dispositions.

clearagent_get_audit

Retrieve the complete audit record for a transaction.

Input:

• txnId (string, required) — Transaction ID

Output:

• txnId — Transaction ID
• verdict — Screening verdict
• screenedAt — Screening timestamp
• screenedBy — Agent that screened
• ruleTriggered — Rule that determined verdict
• review (optional) — Disposition info if reviewed
• reviewedBy (optional) — Officer who reviewed
• disposition (optional) — APPROVED / REJECTED / ESCALATE_SAR
• Full context: amount, chain, counterparty, operator.

Auth: Requires CLEARAGENT_API_KEY.

Billing & Usage

clearagent_get_usage

Get current month billing usage for the authenticated operator.

Input: None

Output:

• plan — "starter" | "pro" | "inactive"
• limit — Screens per month (100 for starter, 10,000 for pro, 0 for inactive)
• used — Screens used this month
• remaining — Screens remaining
• resetAt — ISO timestamp of next reset

Auth: Requires CLEARAGENT_API_KEY.

clearagent_get_alerts

List daily OFAC re-screening alerts. Returns any sanctions list changes or wallet movements requiring attention.

Input: None

Output: Array of alerts with timestamps, affected entities, and recommended actions.

Auth: Requires CLEARAGENT_API_KEY.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | CLEARAGENT_API_KEY | Yes* | KYAOperatorCredential JWT (Bearer token). Required for all authenticated endpoints. | | CLEARAGENT_AGENT_TOKEN | No | KYAAgentCredential JWT. Used by clearagent_screen if not provided in request. |

*Not required for public endpoints (clearagent_health, clearagent_demo_screen).

Examples

Register a New Operator

Tools: clearagent_register_operator
Input:
  legalName: "Acme Payments Inc"
  email: "[email protected]"
  plan: "starter"

Response:

{
  "operatorId": "op_abc123",
  "operatorToken": "eyJhbGc...",
  "agentToken": "eyJhbGc...",
  "plan": "starter",
  "limit": 100,
  "createdAt": "2026-04-02T12:00:00Z"
}

Screen a Transaction

Tools: clearagent_screen
Input:
  cpName: "Alice Corp"
  cpWallet: "0x1234567890abcdef1234567890abcdef12345678"
  chain: "Ethereum"
  amount: 500

Response:

{
  "verdict": "CLEAR",
  "txnId": "txn_xyz789",
  "agentId": "ag_abc123",
  "reason": "Counterparty passed OFAC screening and spend policy checks",
  "riskScore": 12,
  "screenedAt": "2026-04-02T12:00:00Z",
  "responseTimeMs": 23
}

Check Usage

Tools: clearagent_get_usage
Input: (none)

Response:

{
  "plan": "starter",
  "limit": 100,
  "used": 45,
  "remaining": 55,
  "resetAt": "2026-05-02T00:00:00Z"
}

API Base URL

All endpoints are served from https://api.clearagent.dev.

Learn More

• ClearAgent Docs: https://clearagent.dev
• MCP Protocol: https://modelcontextprotocol.io
• API Reference: https://api.clearagent.dev/docs (coming soon)

Support

For issues, feature requests, or questions:

• GitHub: https://github.com/ClearAg3nt
• Email: [email protected]
• Twitter: @clear_agent

License

MIT