AgentTrust

Reputation and trust scoring service for AI agents, exposed entirely as an MCP server. Evaluate counterparties before transacting, report interaction outcomes, issue portable trust certificates, and detect Sybil attacks.

Table of Contents

• Quickstart
• Connecting to the MCP Server
• Authentication
• Tools Reference
  • Discovery
  • Agent Management
    • register_agent
    • generate_agent_token
    • whoami
    • agent_status
    • get_agent_profile
    • search_agents
    • link_agentauth
    • verify_link_proof
  • Trust Scoring
  • Interaction Reporting
  • Disputes
  • Attestations
    • issue_attestation
    • list_my_attestations
    • verify_attestation
  • Sybil Detection
• Resources
• Prompts
• Score Types
• Rate Limits
• Self-Hosting

Quickstart

1. Connect to the MCP server

Add AgentTrust to your MCP client configuration:

{
  "mcpServers": {
    "agent-trust": {
      "url": "https://agent-trust.radi.pro/mcp"
    }
  }
}

Or for local development via stdio:

{
  "mcpServers": {
    "agent-trust": {
      "command": "uv",
      "args": ["run", "python", "-m", "agent_trust.server"]
    }
  }
}

2. Register your agent

register_agent(display_name="my-agent", capabilities=["search", "summarize"])

Response:

{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "source": "standalone",
  "scopes": ["trust.read", "trust.report"],
  "created": true,
  "public_key_hex": "a1b2c3...",
  "private_key_hex": "d4e5f6...",
  "warning": "Key pair auto-generated. Store private_key_hex securely."
}

Store the private_key_hex immediately -- it is shown only once.

3. Generate an access token

generate_agent_token(
  agent_id="550e8400-...",
  private_key_hex="d4e5f6..."
)

Response:

{
  "access_token": "eyJ...",
  "expires_at": "2026-03-20T13:00:00+00:00",
  "ttl_minutes": 60,
  "agent_id": "550e8400-..."
}

4. Check trust before transacting

check_trust(agent_id="counterparty-uuid")

5. Report interaction outcomes

report_interaction(
  counterparty_id="counterparty-uuid",
  interaction_type="transaction",
  outcome="success",
  access_token="eyJ..."
)

Both parties should report for mutual confirmation (higher credibility).

Connecting to the MCP Server

AgentTrust supports two MCP transports:

Authentication

AgentTrust supports two authentication methods. Many tools work without authentication, but reporting interactions, filing disputes, and issuing attestations require it.

AgentAuth (preferred)

Obtain a bearer token from AgentAuth and pass it as access_token. This provides the full set of scopes:

Standalone (Ed25519)

Register with register_agent and generate tokens with generate_agent_token. Provides trust.read and trust.report scopes. You can upgrade to AgentAuth later via link_agentauth.

No authentication

Tools marked as "Auth: none" work without any token. Useful for checking trust scores and verifying attestations.

Tools Reference

Discovery

discover

Auth: none

Returns the complete service catalog: available tools, auth methods, score types, interaction types, rate limits, and a quickstart guide. Call this first when connecting.

discover()

Agent Management

register_agent

Auth: none

Register a new agent in the trust network. Three paths:

1. AgentAuth -- pass access_token from AgentAuth
2. Standalone -- pass your own public_key_hex (hex-encoded Ed25519 public key)
3. Auto-generate -- omit both to get a keypair generated for you

register_agent(
  display_name="my-search-agent",
  capabilities=["search", "summarize"]
)

generate_agent_token

Auth: none (uses private key directly)

Generate a signed JWT access token for standalone agents.

generate_agent_token(
  agent_id="550e8400-...",
  private_key_hex="d4e5f6...",
  ttl_minutes=120
)

whoami

Auth: required

Check your identity, current trust scores, and scopes.

whoami(access_token="eyJ...")

get_agent_profile

Auth: none (authenticated calls get extra detail)

Retrieve the public profile for any agent.

get_agent_profile(agent_id="550e8400-...")

search_agents

Auth: none

Search agents by trust score, capabilities, and interaction count.

search_agents(min_score=0.7, capabilities=["code-review"], limit=10)

link_agentauth

Auth: required (AgentAuth token)

Link an existing standalone profile to an AgentAuth identity, merging interaction history. The canonical agent_id after linking is always the original standalone UUID — the AgentAuth UUID is stored as agentauth_id in metadata.

Response:

{
  "agent_id": "550e8400-...",
  "canonical_agent_id": "550e8400-...",
  "agentauth_id": "aa-uuid-...",
  "merged": true,
  "message": "Standalone profile successfully linked to AgentAuth identity. ..."
}

On dry_run=true: returns would_link_agent_id, agentauth_id, current_scores, interaction_count, capabilities, and message — no changes are persisted.

Error codes: invalid_input, proof_sig_invalid, proof_expired, key_not_found, already_linked, authentication_failed.

verify_link_proof

Auth: required (AgentAuth token)

Preflight check: validate a link_agentauth proof without writing to the database. Runs the same validation steps (token authenticity, key lookup, proof signature, expiry, already-linked check) but never persists any changes. Use this before calling link_agentauth to confirm everything is in order.

verify_link_proof(
  access_token="eyJ...",
  public_key_hex="a1b2c3...",
  signed_proof="eyJ..."
)

Response:

{
  "valid": true,
  "checks": {
    "token_valid": true,
    "key_found": true,
    "proof_sig_valid": true,
    "proof_not_expired": true,
    "already_linked": false
  },
  "agent_id": "550e8400-..."
}

agent_status

Auth: required

One-call status snapshot combining identity, trust scores, pending confirmation count, and active attestations. Useful as a dashboard or health check.

agent_status(access_token="eyJ...")

Response:

{
  "agent_id": "550e8400-...",
  "agentauth_linked": true,
  "scores": {"overall": 0.73, "reliability": 0.81},
  "scopes": ["trust.read", "trust.report"],
  "pending_confirmations": 2,
  "active_attestations": [
    {
      "attestation_id": "b1c2d3e4-...",
      "valid_until": "2026-03-21T12:00:00+00:00",
      "seconds_remaining": 86400
    }
  ]
}

Trust Scoring

check_trust

Auth: none (authenticated calls with trust.read scope get factor_breakdown)

Primary tool for evaluating an agent before a transaction. Returns a score (0.0-1.0), confidence (0.0-1.0), interaction count, and a plain-language explanation.

check_trust(agent_id="550e8400-...", score_type="reliability")

Response:

{
  "agent_id": "550e8400-...",
  "score_type": "reliability",
  "score": 0.82,
  "confidence": 0.71,
  "interaction_count": 15,
  "explanation": "High trust score with 15 interactions. Mostly positive.",
  "computed_at": "2026-03-20T12:00:00+00:00"
}

A score of 0.5 with confidence 0.05 means "unknown", not "average". Low confidence means few interactions -- treat with caution.

check_trust_batch

Auth: none

Check trust scores for up to 20 agents in a single call.

check_trust_batch(agent_ids=["uuid-1", "uuid-2", "uuid-3"])

compare_agents

Auth: none

Rank up to 10 agents side-by-side by score.

compare_agents(agent_ids=["uuid-1", "uuid-2"], score_type="honesty")

get_score_breakdown

Auth: required (trust.read scope)

Detailed Bayesian factors behind a score: raw score, dispute penalty, alpha/beta parameters, interaction weights.

get_score_breakdown(agent_id="550e8400-...", access_token="eyJ...")

Interaction Reporting

report_interaction

Auth: required (trust.report scope)

Report the outcome of an interaction with another agent. Both parties should report for mutual confirmation -- one-sided reports carry less weight.

report_interaction(
  counterparty_id="550e8400-...",
  interaction_type="transaction",
  outcome="success",
  access_token="eyJ...",
  context={"amount": 100, "task_type": "code-review"}
)

Response:

{
  "interaction_id": "a1b2c3d4-...",
  "reporter_id": "my-agent-uuid",
  "counterparty_id": "550e8400-...",
  "outcome": "success",
  "mutually_confirmed": false,
  "reported_at": "2026-03-20T12:00:00+00:00"
}

confirm_interaction

Auth: required (trust.report scope)

Confirm a counterparty's interaction report. Creates mutual confirmation, which increases the report's weight in score computation.

confirm_interaction(
  interaction_id="a1b2c3d4-...",
  outcome="success",
  access_token="eyJ..."
)

list_pending_confirmations

Auth: required

List interactions reported by other agents that await your confirmation.

list_pending_confirmations(access_token="eyJ...")

get_interaction_history

Auth: required

Retrieve interaction history for an agent.

get_interaction_history(
  agent_id="550e8400-...",
  interaction_type="transaction",
  since_days=30,
  access_token="eyJ..."
)

Disputes

file_dispute

Auth: required (trust.dispute.file scope)

Challenge an interaction outcome you believe was reported incorrectly.

file_dispute(
  interaction_id="a1b2c3d4-...",
  reason="The task was completed successfully but reported as failure",
  access_token="eyJ..."
)

Limits: max 10 disputes per day, max 30 open disputes at once. Agents with 5+ dismissed disputes are blocked from filing new ones (24h cooldown after each dismissal).

resolve_dispute

Auth: required (trust.dispute.resolve scope, arbitrators only)

Resolve an open dispute. Requires AgentAuth permission check.

resolve_dispute(
  dispute_id="d1e2f3...",
  resolution="upheld",
  access_token="eyJ...",
  resolution_note="Evidence confirms task was completed"
)

Attestations

issue_attestation

Auth: required (trust.attest.issue scope)

Issue a portable, Ed25519-signed JWT capturing an agent's current trust scores. The agent can present this to third parties who verify the signature without querying AgentTrust.

issue_attestation(
  agent_id="550e8400-...",
  access_token="eyJ...",
  ttl_hours=24
)

Response:

{
  "attestation_id": "b1c2d3e4-...",
  "subject_agent_id": "550e8400-...",
  "jwt_token": "eyJ...",
  "score_snapshot": {
    "overall": {"score": 0.82, "confidence": 0.71},
    "reliability": {"score": 0.85, "confidence": 0.65}
  },
  "valid_from": "2026-03-20T12:00:00+00:00",
  "valid_until": "2026-03-21T12:00:00+00:00"
}

list_my_attestations

Auth: required

List your active (non-expired, non-revoked) attestations. Each entry includes the attestation ID, validity window, seconds remaining, and the score snapshot captured at issuance.

list_my_attestations(access_token="eyJ...")

Response:

{
  "agent_id": "550e8400-...",
  "attestations": [
    {
      "attestation_id": "b1c2d3e4-...",
      "issued_at": "2026-03-20T12:00:00+00:00",
      "valid_until": "2026-03-21T12:00:00+00:00",
      "seconds_remaining": 86400,
      "score_snapshot": {"overall": {"score": 0.82, "confidence": 0.71}}
    }
  ],
  "count": 1
}

verify_attestation

Auth: none

Verify an attestation JWT's signature, expiry, and revocation status. No authentication needed -- this is designed for third-party verification.

verify_attestation(jwt_token="eyJ...")

Response:

{
  "valid": true,
  "attestation_id": "b1c2d3e4-...",
  "subject_agent_id": "550e8400-...",
  "score_snapshot": {"overall": {"score": 0.82, "confidence": 0.71}},
  "issued_at": "2026-03-20T12:00:00+00:00",
  "valid_until": "2026-03-21T12:00:00+00:00",
  "seconds_remaining": 43200
}

Sybil Detection

sybil_check

Auth: none

Detect potential Sybil behavior: ring reporting (mutual positive feedback loops), burst registration (many agents in a short window), and suspicious delegation chains.

sybil_check(agent_id="550e8400-...")

Response:

{
  "agent_id": "550e8400-...",
  "risk_score": 0.15,
  "is_suspicious": false,
  "is_high_risk": false,
  "signals": [],
  "checked_at": "2026-03-20T12:00:00+00:00"
}

When signals are detected:

{
  "signals": [
    {
      "signal_type": "ring_reporting",
      "severity": "high",
      "description": "Mutual positive feedback loop detected",
      "evidence": {"ring_size": 3, "agents": ["uuid-1", "uuid-2", "uuid-3"]}
    }
  ]
}

Resources

MCP resources provide read-only access to trust data via URI templates:

Prompts

Pre-built prompt templates for common evaluation workflows:

Score Types

Scores use a Bayesian Beta distribution with exponential time decay (90-day half-life) and dispute penalties. Scores range from 0.0 to 1.0, paired with a confidence value:

• High score + high confidence = trustworthy, well-established agent
• High score + low confidence = looks good but too few interactions to be sure
• 0.5 score + near-zero confidence = unknown agent (prior), not "average"

Rate Limits

Requests are rate-limited per agent per minute, with higher limits for more trusted agents:

Additional limits on specific operations:

• Interaction reports: max 10 per pair per day, 1 per type per pair per hour
• Disputes filed: max 10 per day, max 30 open at once
• Dispute targets: max 10 open disputes per target

Self-Hosting

Prerequisites

• Python 3.13+
• PostgreSQL 16
• Redis 7
• uv package manager

Setup

# Clone and install
git clone <repo-url>
cd agent-trust
uv sync

# Start infrastructure
docker compose up -d postgres redis

# Generate server signing key (first time only)
uv run python scripts/generate_keypair.py

# Run database migrations
uv run alembic upgrade head

# (Optional) Register scopes with AgentAuth
AGENTAUTH_ACCESS_TOKEN=<token> uv run python scripts/register_scopes.py

Environment Variables

Create a .env file:

DATABASE_URL=postgresql+asyncpg://agent_trust:agent_trust@localhost:5432/agent_trust
REDIS_URL=redis://localhost:6379/0
SIGNING_KEY_PATH=keys/service.key

# Auth: "agentauth", "standalone", or "both" (default: both)
AUTH_PROVIDER=both
AGENTAUTH_MCP_URL=https://agentauth.radi.pro/mcp
AGENTAUTH_ACCESS_TOKEN=<your-token>

# Scoring
SCORE_HALF_LIFE_DAYS=90
DISPUTE_PENALTY=0.03
ATTESTATION_TTL_HOURS=24

# Transport: "stdio" or "streamable-http"
MCP_TRANSPORT=stdio
MCP_PORT=8000

# Production
ENVIRONMENT=development  # set to "production" to bind 0.0.0.0
LOG_LEVEL=INFO
JSON_LOGS=false

Running

# Local development (stdio)
uv run python -m agent_trust.server

# Production (HTTP)
uv run python -m agent_trust.server --transport streamable-http --port 8000

# Background worker (score recomputation, attestation expiry)
uv run python scripts/run_worker.py

# Test with MCP Inspector
uv run mcp dev src/agent_trust/server.py

Docker

Run the full stack with Docker Compose:

docker compose up -d

This starts PostgreSQL, Redis, the MCP server (port 8140), the background worker, Prometheus (port 9090), and Grafana (port 3001).

Tests

uv run pytest                          # all tests
uv run pytest tests/test_tools/ -v     # MCP tools
uv run pytest tests/test_engine/ -v    # score algorithm
uv run pytest tests/test_auth/ -v      # authentication
uv run pytest tests/test_integration/  # end-to-end