MCP Trust Gateway

Trust, reputation, and economic accountability for MCP — the missing layer above OAuth.

MCP's OAuth 2.1 foundation answers who is this agent? This gateway answers the harder question: authenticated, but trustworthy? It sits between MCP clients and upstream MCP servers as a protocol-transparent proxy, enriching every tool invocation with trust evaluation powered by A2A Settlement Exchange reputation, KYA tiers, spending limits, and delegation chains.

MCP Client                                          Upstream MCP Servers
(Claude, Cursor, agents)                            (any MCP server)
        │                                                   ▲
        │  MCP Streamable HTTP                              │
        │  + OAuth 2.1 / PKCE                               │
        ▼                                                   │
┌───────────────────────────────────────────────────────────────┐
│                     MCP Trust Gateway                         │
│                                                               │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────────┐ │
│  │ OAuth 2.1   │  │ Trust        │  │ Pre-Auth Tool        │ │
│  │ + Settlement│  │ Evaluator    │  │ Discovery            │ │
│  │   Claims    │  │ (KYA + EMA)  │  │ (/.well-known/       │ │
│  │             │  │              │  │  mcp-tools)          │ │
│  └──────┬──────┘  └──────┬───────┘  └──────────────────────┘ │
│         │                │                                    │
│  ┌──────┴──────┐  ┌──────┴───────┐                            │
│  │ RFC 8693    │  │ Scope-to-KYA │                            │
│  │ Token       │  │ Tier Mapper  │                            │
│  │ Exchange    │  │              │                            │
│  │ + Trust     │  │              │                            │
│  │   Decay     │  │              │                            │
│  └─────────────┘  └──────────────┘                            │
└───────────────────────────┬───────────────────────────────────┘
                            │ queries
                            ▼
                ┌───────────────────────┐
                │  A2A Settlement       │
                │  Exchange             │
                │  (reputation, KYA,    │
                │   agent directory)    │
                └───────────────────────┘

The Gap

MCP has made real progress on authentication. OAuth 2.1 with PKCE, Streamable HTTP transport, the MCP Connector in Claude's API, and enterprise IdP integrations from Auth0 and AWS. The identity problem is largely solved.

But four gaps remain — and they all sit above authentication:

The common thread: authentication is necessary but not sufficient for autonomous agents. OAuth says "this token is valid." The trust gateway adds "and here's how much you should trust the agent presenting it."

Related MCP server: Proofpane

How It Works

1. Trust-Enriched OAuth

The gateway implements MCP's OAuth 2.1 flow (Authorization Code + PKCE) but enriches issued tokens with settlement claims:

{
  "sub": "agent:analytics-bot-7f3a",
  "scope": "settlement:transact mcp:tool:invoke",
  "https://a2a-settlement.org/claims": {
    "agent_id": "analytics-bot-7f3a",
    "org_id": "org-acme-corp",
    "kya_level": 1,
    "reputation": 0.87,
    "spending_limits": { "per_transaction": 500, "per_day": 5000 },
    "counterparty_policy": { "require_min_reputation": 0.7 },
    "delegation": {
      "chain": [{ "principal": "user:julie@acme.com", "delegated_at": "2026-03-01T09:00:00Z" }],
      "transferable": false
    }
  }
}

The token carries identity (OAuth) and trustworthiness (settlement claims) in a single artifact.

2. Pre-Auth Tool Discovery

Agents can discover available tools and their trust requirements before authenticating:

GET /.well-known/mcp-tools

{
  "tools": [
    {
      "name": "query_database",
      "description": "Run read-only SQL queries",
      "required_kya_level": 0,
      "required_reputation": 0.0,
      "required_scope": "mcp:read"
    },
    {
      "name": "execute_trade",
      "description": "Submit a trade order",
      "required_kya_level": 2,
      "required_reputation": 0.8,
      "required_scope": "mcp:tool:financial"
    }
  ]
}

Clients evaluate what permissions they need before initiating OAuth. No more blind authorization prompts.

3. Trust Evaluation on Every Call

On every proxied tools/call, the gateway evaluates:

• KYA tier >= tool's required tier (identity verification depth)

• EMA reputation >= tool's minimum threshold (track record)

• Spending limits not exceeded (economic guardrails)

• Counterparty policy allows the upstream server (organizational constraints)

• Delegation chain is intact and transferable flag permits the hop

If trust is insufficient, the gateway returns a structured denial with an upgrade path:

{
  "error": "trust_insufficient",
  "required_kya_level": 2,
  "current_kya_level": 1,
  "upgrade_url": "https://exchange.example.com/kya/upgrade",
  "message": "This tool requires AUDITABLE identity verification. Current level: ORGANIZATIONAL."
}

4. Trust-Decaying Token Exchange

For multi-hop scenarios (agent A delegates to agent B which calls tool C), the gateway implements RFC 8693 token exchange extended with trust decay:

Agent A (reputation: 0.92)
    │
    │  RFC 8693 token exchange
    │  trust_score = 0.92 × 0.85 decay = 0.782
    ▼
Agent B (delegated token, effective trust: 0.782)
    │
    │  second hop
    │  trust_score = 0.782 × 0.85 decay = 0.665
    ▼
Tool C (requires min reputation: 0.6) ✓ allowed

Each hop in the delegation chain reduces effective trust via EMA-weighted decay. Scopes narrow (never widen). Spending limits reduce proportionally. The result: "yes this token is valid, but the further it travels from the original principal, the less authority it carries."

5. Scope-to-Trust-Tier Mapping

Instead of arbitrary server-defined scope strings, the gateway maps MCP tool categories to trust tiers:

This gives scopes meaning grounded in verified identity, not server whim.

Install

pip install -e .

Or from git:

pip install git+https://github.com/a2a-settlement/mcp-trust-gateway.git

Quick Start

1. Start the Gateway

export A2A_EXCHANGE_URL=http://localhost:3000
export MCP_TRUST_GATEWAY_PORT=3100
python -m mcp_trust_gateway

The gateway starts on port 3100, proxying to upstream MCP servers registered in the exchange's agent directory.

Token issuance uses grant_type=client_credentials unless OAUTH_AUTHORIZE_ENABLED=true. See Production configuration.

2. Connect Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "trust-gateway": {
      "url": "http://localhost:3100/mcp",
      "authorization": {
        "type": "oauth2",
        "authorization_url": "http://localhost:3100/oauth/authorize",
        "token_url": "http://localhost:3100/oauth/token"
      }
    }
  }
}

3. Connect Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "trust-gateway": {
      "url": "http://localhost:3100/mcp",
      "env": {
        "A2A_EXCHANGE_URL": "http://localhost:3000"
      }
    }
  }
}

Configuration

Production configuration

Install with the tested dependency versions: pip install -c constraints.txt -e .

A2A_EXCHANGE_TIMEOUT_S (default 15) bounds each exchange call. The exchange rejects an invalid API key only after checking it against every account's bcrypt hash, which takes several seconds.

SettleBridge verifies RS256 tokens from this gateway. Configure:

• OAUTH_ALGORITHM=RS256

• OAUTH_SIGNING_KEY_FILE pointing at an unencrypted PEM private key (this takes precedence over OAUTH_SIGNING_KEY)

• OAUTH_ISSUER and OAUTH_AUDIENCE to the values SettleBridge expects

• A2A_EXCHANGE_URL so the gateway can reach GET /v1/exchange/balance and GET /v1/accounts/{id}/card

Startup refuses to run if an asymmetric algorithm is set without a matching private key, if the algorithm is none, or if an HMAC key is shorter than 32 bytes. Those errors do not include key material.

Agents obtain tokens with the client-credentials grant. client_id is the exchange account id and client_secret is that bot's ate_ API key, in a form body, a JSON body, or HTTP Basic. The secret is sent once to the exchange balance endpoint and is not stored or logged. The account must be active and the balance account_id must match client_id. KYA comes from the public card (kya_level_verified); a missing card is KYA 0. A card or exchange failure fails closed.

curl -u "$ACCOUNT_ID:$A2A_API_KEY" \
  -d "grant_type=client_credentials" \
  -d "scope=mcp:read mcp:tool:financial" \
  http://127.0.0.1:3100/oauth/token

When MCP_TRUST_FINANCIAL_ALLOWLIST is non-empty, mcp:tool:financial is issued only to those agent ids, including agents at KYA 0. Everyone else is denied that scope even at a higher KYA level. Other scopes still follow KYA rules. When the list is empty, financial scope requires KYA level 2 (AUDITABLE). The token's trust.kya_level is always the agent's real KYA level.

The public key is published at GET /.well-known/jwks.json (kty, n, e, kid, alg, use=sig) for asymmetric keys. HMAC deployments return 404 there. Token headers include that kid.

GET /oauth/authorize and grant_type=authorization_code return 400 unless OAUTH_AUTHORIZE_ENABLED=true. The enabled code flow is unchanged and does not verify an API key.

Token exchange does not authenticate the delegate. It only narrows the parent token's scopes. With a non-empty financial allowlist, mcp:tool:financial is kept only when the parent already has it and the requested actor id is listed. An explicit request for financial by an unlisted actor is rejected. The actor id is not proof of identity.

Project Structure

mcp-trust-gateway/
  SPEC.md                          # RFC-style trust layer specification
  README.md
  pyproject.toml
  src/mcp_trust_gateway/
    __init__.py
    __main__.py                    # Entry point
    config.py                      # Environment configuration
    server.py                      # MCP server (client-facing)
    proxy.py                       # MCP client (upstream-facing proxy)
    oauth/
      provider.py                  # client_credentials and optional PKCE
      keys.py                      # RS256/HMAC signing and JWKS
      token_exchange.py            # RFC 8693 with trust decay
      metadata.py                  # RFC 8414 / RFC 9728 metadata
    trust/
      evaluator.py                 # Trust evaluation engine
      scope_mapper.py              # MCP scope <-> SettlementScope <-> KYA tier
      trust_decay.py               # EMA-weighted trust decay for delegation
    discovery/
      well_known.py                # /.well-known/mcp-tools endpoint
      registry.py                  # Exchange directory -> tool manifest bridge
  tests/
  examples/

Design Principles

Protocol-transparent proxy. The gateway does not define its own MCP tools. It proxies upstream MCP servers and adds trust evaluation as middleware. Any existing MCP server works without modification.

Reuse, don't rebuild. OAuth token validation, scope checking, claims parsing, spending limits, and delegation chains come from a2a-settlement-auth. Reputation and KYA queries come from the a2a-settlement SDK. The gateway is the glue.

Spec-first. The SPEC.md is the primary deliverable — it's what gets proposed back to the MCP ecosystem as the missing trust layer. The code is the reference implementation.

Additive, not competitive. This builds on MCP's OAuth 2.1 foundation. It does not replace it, fork it, or compete with it. It answers the question OAuth was never designed to answer: should you trust this agent?

Related Projects

This gateway vs a2a-settlement-mcp: The MCP server exposes settlement operations as tools (create escrow, check balance, etc.). This gateway evaluates trust on MCP tool invocations. They are complementary — you might use the MCP server behind this gateway, or use the gateway to protect any other MCP server.

Contributing

See CONTRIBUTING.md. The most impactful contributions right now are to the SPEC.md — helping formalize the trust layer so it can be proposed upstream to the MCP ecosystem.

License

MIT. See LICENSE.