How CapiscIO Works¶

CapiscIO provides a complete trust infrastructure for AI agents. Here's how the pieces fit together.

The Problem¶

AI agents are exploding in capability and prevalence. But there's a trust gap:

Agent A says: "I'm Weather Bot v2.1"

Agent B asks: "Should I trust this?"

• Self-descriptions can be forged
• API keys prove payment, not identity
• No standard verification mechanism

The Solution: Three Layers of Trust¶

CapiscIO provides three products that work together:

How they connect: Core produces badges → SDK uses badges at runtime → MCP Guard extends SDK for MCP tools

1. CapiscIO Core (CLI)¶

What it does: Build-time validation and badge management.

# Validate your A2A agent card
capiscio validate agent-card.json
# ✅ Score: 95/100 (A+)

# Generate cryptographic keys
capiscio key gen --show-did
# ✅ did:key:z6Mk...

# Issue a trust badge
capiscio badge issue --self-sign
# ✅ Badge written to badge.jwt

Use cases:

• CI/CD validation gates
• Pre-deployment checks
• Badge issuance pipeline
• Key management

CLI Reference

2. CapiscIO SDK (Python)¶

What it does: Runtime security enforcement for your agent.

from capiscio_sdk import SimpleGuard, verify_badge

# 1. Sign outbound requests
guard = SimpleGuard()
headers = guard.make_headers({"sub": agent_did})

# 2. Verify incoming badges
result = verify_badge(
    token,
    trusted_issuers=["https://registry.capisc.io"],
)
if result.valid:
    print(f"Verified: {result.claims.subject}")
    print(f"Trust Level: {result.claims.trust_level.value}")

Use cases:

• API authentication & authorization
• Request signing
• Trust level enforcement
• Audit logging

Python SDK

3. MCP Guard¶

What it does: Trust-level authorization for Model Context Protocol tool calls.

from capiscio_mcp import guard

# Protect individual tools
@guard(min_trust_level=2)
async def read_database(query: str):
    """Only Level 2+ agents can query."""
    return await db.execute(query)

@guard(min_trust_level=3)
async def write_database(table: str, data: dict):
    """Only Level 3+ agents can write."""
    return await db.insert(table, data)

Use cases:

• Protecting MCP servers
• Tool-level authorization
• Client-server identity verification
• Cryptographic audit trails

MCP Guard

The Trust Flow¶

Here's how trust flows through a typical interaction:

Trust Levels¶

CapiscIO uses a 5-level trust hierarchy (RFC-002 §5):

The key insight: Higher levels require more verification but enable more sensitive operations.

from capiscio_sdk import verify_badge, TrustLevel

# Verify a badge and check trust level
result = verify_badge(token, trusted_issuers=["https://registry.capisc.io"])

if result.valid:
    level = int(result.claims.trust_level.value)
    if level >= 2:
        # Domain-verified agent — allow production access
        pass
    elif level >= 3:
        # Org-verified agent — allow enterprise operations
        pass

Installation Paths¶

Depending on your use case:

pip install capiscio   # or: npm install -g capiscio
capiscio validate agent-card.json

pip install capiscio-sdk

from capiscio_sdk import SimpleGuard
guard = SimpleGuard()

pip install capiscio-mcp

from capiscio_mcp import guard
@guard(min_trust_level=2)
async def my_tool(): ...

# .github/workflows/validate.yml
- uses: capiscio/validate-a2a@v2
  with:
    path: agent-card.json
    min-score: 80

What's Next?¶