diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 7edcc17..4c38229 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -88,6 +88,15 @@ jobs: path: capiscio-rfcs fetch-depth: 0 token: ${{ secrets.GITHUB_TOKEN }} + + - name: Checkout capiscio-mcp-python + uses: actions/checkout@v4 + with: + repository: capiscio/capiscio-mcp-python + path: capiscio-mcp-python + ref: fix/rfc-links # TODO: Remove after capiscio/capiscio-mcp-python#4 is merged + fetch-depth: 0 + token: ${{ secrets.GITHUB_TOKEN }} - name: Set up Python uses: actions/setup-python@v5 diff --git a/docs/concepts/index.md b/docs/concepts/index.md index 2ef7a6b..b171899 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -9,7 +9,39 @@ Understand how CapiscIO works under the hood. These docs explain the **why** and --- -## Core Concepts +## Identity & Trust + +
+ +- :material-identifier:{ .lg .middle } **Identity & DIDs** + + --- + + Decentralized identifiers give your agent a permanent, cryptographically verifiable identity. + + [:octicons-arrow-right-24: Learn about DIDs](../identity/index.md) + +- :material-certificate:{ .lg .middle } **Trust Badges** + + --- + + Cryptographic credentials that attest to your agent's identity verification level (0-4). + + [:octicons-arrow-right-24: Understanding Badges](../trust/index.md) + +- :material-key:{ .lg .middle } **Trust Levels** + + --- + + The five-level verification hierarchy—from self-signed to extended validation. + + [:octicons-arrow-right-24: Trust Levels](trust-model.md) + +
+ +--- + +## Validation & Scoring
@@ -29,13 +61,13 @@ Understand how CapiscIO works under the hood. These docs explain the **why** and [:octicons-arrow-right-24: Understanding Scores](scoring.md) -- :material-key:{ .lg .middle } **Trust Model** +
- --- +--- - How Ed25519 keys, trust stores, and cryptographic verification work. The SSH-like model explained. +## Runtime Security - [:octicons-arrow-right-24: Trust Model](trust-model.md) +
- :material-shield-check:{ .lg .middle } **Enforcement** @@ -45,6 +77,30 @@ Understand how CapiscIO works under the hood. These docs explain the **why** and [:octicons-arrow-right-24: Enforcement](enforcement.md) +- :material-tools:{ .lg .middle } **MCP Security** + + --- + + RFC-006 (tool authorization) and RFC-007 (server verification) for Model Context Protocol. + + [:octicons-arrow-right-24: MCP Security](mcp-security.md) + +
+ +--- + +## Infrastructure + +
+ +- :material-server:{ .lg .middle } **Agent Registry** + + --- + + The central registry for agent discovery, DID resolution, and badge verification. + + [:octicons-arrow-right-24: Registry](../registry/index.md) +
--- @@ -91,6 +147,7 @@ Understand how CapiscIO works under the hood. These docs explain the **why** and | **[Scoring](scoring.md)** | "How good is this agent across compliance, trust, availability?" | | **[Trust Model](trust-model.md)** | "How do I manage who my agent trusts?" | | **[Enforcement](enforcement.md)** | "How do I protect my agent at runtime?" | +| **[MCP Guard](../mcp-guard/index.md)** | "How do I secure MCP tools?" | --- @@ -103,6 +160,8 @@ For the formal technical specifications, see the CapiscIO RFCs: | **[RFC-001](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/001-agcp.md)** | Agent Governance Control Plane (AGCP) | ✅ Approved | | **[RFC-002](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/002-trust-badge.md)** | Trust Badge Specification | ✅ Approved | | **[RFC-003](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/003-key-ownership-proof.md)** | Key Ownership Proof Protocol | ✅ Approved | +| **[RFC-006](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/006-mcp-tool-authority-evidence.md)** | MCP Tool Authority Evidence | ✅ Approved | +| **[RFC-007](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/007-mcp-server-identity-discovery.md)** | MCP Server Identity Discovery | ✅ Approved | [:octicons-arrow-right-24: Browse All RFCs](https://github.com/capiscio/capiscio-rfcs){ .md-button } diff --git a/docs/concepts/mcp-security.md b/docs/concepts/mcp-security.md new file mode 100644 index 0000000..d3be62b --- /dev/null +++ b/docs/concepts/mcp-security.md @@ -0,0 +1,150 @@ +# MCP Security + +The Model Context Protocol (MCP) enables powerful tool access for AI agents. CapiscIO's **MCP Guard** brings trust infrastructure to MCP with two complementary specifications. + +## The Problem + +MCP servers expose powerful tools to autonomous agents—file systems, databases, APIs, code execution. But MCP itself doesn't define: + +- **Who** is calling a tool (authentication) +- **Whether** they should have access (authorization) +- **What** happened for post-incident review (audit) + +## The Solution: Two RFCs + +MCP Guard implements two CapiscIO specifications: + +### RFC-006: MCP Tool Authority and Evidence + +**Server-side protection.** Define trust level requirements for individual tools. + +```python +from capiscio_mcp import guard + +@guard(min_trust_level=2) +async def read_database(query: str) -> list[dict]: + """Only Level 2+ agents can query the database.""" + return await db.execute(query) + +@guard(min_trust_level=3) +async def write_database(table: str, data: dict): + """Only Level 3+ (org-validated) agents can write.""" + return await db.insert(table, data) +``` + +**Key features:** + +- **Trust level enforcement** — Require minimum verification level +- **Evidence logging** — Cryptographic audit trail for every call +- **Parameter hashing** — PII-safe evidence records +- **Async and sync** — Both decorator styles supported + +[:octicons-arrow-right-24: RFC-006 Full Specification](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/006-mcp-tool-authority-evidence.md) + +--- + +### RFC-007: MCP Server Identity Disclosure + +**Client-side verification.** Verify MCP server identity before connecting. + +```python +from capiscio_mcp import verify_server, ServerState + +result = await verify_server( + server_did="did:web:mcp.example.com", + server_badge="eyJhbGc...", + transport_origin="https://mcp.example.com", +) + +if result.state == ServerState.VERIFIED_PRINCIPAL: + print(f"✓ Trusted server at Level {result.trust_level}") +else: + print("⚠ Server identity not verified") +``` + +**Key features:** + +- **Server identity verification** — Confirm who you're connecting to +- **Transport binding** — Verify server controls the transport endpoint +- **Trust level inspection** — Check server's verification level +- **Three states** — VERIFIED_PRINCIPAL, DECLARED_PRINCIPAL, UNVERIFIED_ORIGIN + +[:octicons-arrow-right-24: RFC-007 Full Specification](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/007-mcp-server-identity-discovery.md) + +--- + +## How They Work Together + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ MCP Security Flow │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ MCP CLIENT MCP SERVER │ +│ ┌─────────────┐ ┌─────────────┐ │ +│ │ Agent A │ │ File Tool │ │ +│ │ (Level 2) │ │ Server │ │ +│ └─────────────┘ └─────────────┘ │ +│ │ │ │ +│ │ 1. Verify server identity │ │ +│ │ (RFC-007) │ │ +│ │ ─────────────────────────────────────>│ │ +│ │ │ │ +│ │ 2. Call tool with badge │ │ +│ │ ─────────────────────────────────────>│ │ +│ │ │ │ +│ │ 3. Guard evaluates │ │ +│ │ (RFC-006) │ │ +│ │ ▼ │ +│ │ ┌─────────────┐ │ +│ │ │ @guard(2) │ │ +│ │ │ → ALLOW │ │ +│ │ │ → log audit │ │ +│ │ └─────────────┘ │ +│ │ │ │ +│ │ 4. Return result │ │ +│ │ <─────────────────────────────────────│ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +1. **Client verifies server** using RFC-007 before connecting +2. **Client calls tool** with their trust badge attached +3. **Server guard evaluates** the caller's trust level (RFC-006) +4. **Evidence logged** regardless of allow/deny decision + +--- + +## Trust Levels in MCP Context + +| Level | Server Use | Client Use | +|:-----:|------------|------------| +| **0** | Development servers | Anonymous tool access | +| **1** | Personal project servers | Registered agents | +| **2** | Production read-only tools | Domain-verified agents | +| **3** | Write operations | Org-verified agents | +| **4** | Admin tools | Enterprise agents | + +--- + +## Next Steps + +
+ +- [:material-shield-check: **Protect Your Tools**](../../mcp-guard/guides/server-side/) + + Add `@guard` to your MCP server tools + +- [:material-check-decagram: **Verify Servers**](../../mcp-guard/guides/client-side/) + + Implement server verification in your MCP client + +- [:material-file-document: **Evidence Logging**](../../mcp-guard/guides/evidence/) + + Set up cryptographic audit trails + +- [:material-api: **API Reference**](../../reference/sdk-python/mcp/) + + Complete MCP Guard API documentation + +
diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index cc369e3..338834c 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -53,6 +53,16 @@ npm install -g capiscio # or: pip install capiscio [:octicons-arrow-right-24: Add Security](secure/1-intro.md) +- :material-tools:{ .lg .middle } **Protect MCP Tools** + + --- + + Add tool-level authorization to Model Context Protocol servers. + + **10 minutes** · Intermediate + + [:octicons-arrow-right-24: MCP Guard Quickstart](../mcp-guard/getting-started/quickstart.md) + - :material-pipe:{ .lg .middle } **CI/CD Integration** --- diff --git a/docs/how-to/index.md b/docs/how-to/index.md index ff001cb..3f0fde2 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -47,6 +47,17 @@ Task-oriented guides for specific problems. Each guide is self-contained with co --- +## :material-tools: MCP Guard + +| Guide | What You'll Do | Time | +|-------|----------------|------| +| [Protect MCP Tools](../mcp-guard/guides/server-side.md) | Add `@guard` decorator to MCP tools | 5 min | +| [Verify MCP Servers](../mcp-guard/guides/client-side.md) | Verify server identity before connecting | 5 min | +| [Evidence Logging](../mcp-guard/guides/evidence.md) | Log tool calls for compliance | 5 min | +| [MCP SDK Integration](../mcp-guard/guides/mcp-integration.md) | Integrate with official MCP SDK | 10 min | + +--- + ## :material-pipe: CI/CD | Guide | What You'll Do | Time | diff --git a/docs/index.md b/docs/index.md index 653a524..e279a0b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,57 +10,10 @@ hide: --- # CapiscIO @@ -68,358 +21,176 @@ hide:

The Authority Layer for AI Agents

-Like Let's Encrypt revolutionized HTTPS, CapiscIO brings verifiable identity and trust to the agent economy. Give your agent a DID, earn trust badges, be discovered. +Like Let's Encrypt revolutionized HTTPS, CapiscIO brings verifiable identity and trust to the agent economy. Cryptographic proof of who your agent is—and who it can trust.

-Get Your Agent's Identity -Quick Start +Get Started +How It Works
--- -## The Three Pillars +## What Do You Want to Do?
-- :material-identifier:{ .lg .middle } **Decentralized Identity** +- :material-check-decagram:{ .lg .middle } **Validate My Agent Card** --- - Every agent gets a **DID** (Decentralized Identifier) — a globally unique, cryptographically verifiable identity that travels with your agent. + Check if your A2A agent card is compliant and production-ready. - ``` - did:web:registry.capisc.io:agents:my-weather-bot - ``` - - - W3C standard — interoperable everywhere - - Cryptographic proof — unforgeable - - Portable — move providers, keep identity + [:octicons-arrow-right-24: Start Validating](getting-started/validate/1-intro.md) - [:octicons-arrow-right-24: Learn about DIDs](identity/index.md) - -- :material-certificate:{ .lg .middle } **Trust Badges** +- :material-shield-lock:{ .lg .middle } **Secure Agent Communication** --- - Earn **trust levels 0-4** based on identity verification depth. Like SSL certificates for agents. - - | Level | Verification | - |:-----:|--------------| - | 0 | Self-signed | - | 1 | Email verified | - | 2 | Domain validated | - | 3 | Organization validated | - | 4 | Extended validation | + Add authentication, signing, and trust enforcement to your agent. - [:octicons-arrow-right-24: Get a Trust Badge](trust/index.md) + [:octicons-arrow-right-24: Add Security](getting-started/secure/1-intro.md) -- :material-api:{ .lg .middle } **Registry API** +- :material-tools:{ .lg .middle } **Protect MCP Tools** --- - REST API for managing agents, issuing badges, and resolving DIDs. - - - Agent CRUD operations - - Badge issuance and verification - - DID resolution - - Public status endpoints - - [:octicons-arrow-right-24: Registry API](registry/index.md) - -
- ---- - -## Quick Start + Add trust-level authorization to your Model Context Protocol servers. -
+ [:octicons-arrow-right-24: MCP Guard](mcp-guard/getting-started/quickstart.md) -```bash -# 1. Install CLI -npm install -g capiscio # or: pip install capiscio +- :fontawesome-solid-gears:{ .lg .middle } **Add to CI/CD Pipeline** -# 2. Initialize your agent -capiscio init - -# 3. Validate your agent card -capiscio validate -``` - -``` -✅ Validation passed! + --- -Compliance: 95/100 (A+) -Trust: 78/100 (Good) + Automate validation with GitHub Actions, GitLab CI, or Jenkins. -Agent card is valid and ready to use. -``` + [:octicons-arrow-right-24: CI/CD Setup](getting-started/cicd/1-intro.md)
-[:material-rocket-launch: Full Getting Started Guide](getting-started/index.md){ .md-button .md-button--primary } -[:material-download: Download Samples](samples.md){ .md-button } - --- -## Why CapiscIO? - -
- -### The Problem - -AI agents are proliferating. But there's no standard way to: - -- **Verify identity** — Is this really the agent it claims to be? -- **Establish trust** — Can I trust this agent with my data? -- **Validate compliance** — Does this agent card meet standards? - -API keys prove you paid. OAuth tokens expire. Self-descriptions can be forged. - -### The Solution - -CapiscIO provides the **trust infrastructure** for the agent economy: - -| Component | What It Solves | -|-----------|---------------| -| **DID Identity** | Permanent, verifiable, portable agent identity | -| **Trust Badges** | Tiered verification like SSL certificates | -| **Validation Engine** | Multi-dimensional agent card scoring | -| **SDK/CLI** | Frictionless integration for developers | - -**Result:** Agents can prove who they are, establish trust, and find each other. - -
- ---- +## The CapiscIO Stack -## Developer-First Design +Three products that work together to secure the agent economy: -We obsess over developer experience. Every feature works in **three commands or less**. +
-=== "Generate Identity" +- :material-console:{ .lg .middle } **CapiscIO Core** - ```bash - capiscio key gen - # ✅ did:key:z6Mk... generated - ``` + --- -=== "Validate Agent Card" + **CLI & validation engine** — Validate agent cards, generate keys, issue badges. ```bash + pip install capiscio # or npm install -g capiscio capiscio validate agent-card.json - # ✅ Validation passed: 95/100 (A+) ``` -=== "Issue Badge" + [:octicons-arrow-right-24: CLI Reference](reference/cli/index.md) - ```bash - capiscio badge issue --self-sign - # ✅ Badge issued with did:key identity - ``` +- :material-language-python:{ .lg .middle } **CapiscIO SDK** -=== "Add to Your App" + --- + + **Runtime security** — Sign requests, verify badges, enforce trust in your code. ```python from capiscio_sdk import SimpleGuard - - guard = SimpleGuard(dev_mode=True) # That's it! - - @app.post("/task") - @guard.protect - async def handle(request): - # Requests are verified automatically - pass + guard = SimpleGuard(dev_mode=True) ``` ---- - -## Trust Hierarchy - -
-
- Level 0
- Self-Signed -
-
- Level 1
- Registered -
-
- Level 2
- Domain Validated -
-
- Level 3
- Org Validated -
-
- Level 4
- Extended -
-
+ [:octicons-arrow-right-24: Python SDK](reference/sdk-python/index.md) -Higher levels = more verification = more trust. Choose what's right for your use case: - -| Use Case | Recommended Level | -|----------|-------------------| -| Development & testing | 0 (self-signed) | -| Personal projects | 1 (registered) | -| Production APIs | 2 (domain validated) | -| Enterprise integrations | 3 (org validated) | -| Financial, healthcare | 4 (extended validation) | - -[:octicons-arrow-right-24: Learn about Trust Levels](trust/index.md) - ---- - -## What You Can Build - -
- -- :material-robot:{ .lg .middle } **Secure Agent Networks** - - --- - - Build multi-agent systems where agents verify each other's identity before communicating. - -- :material-api:{ .lg .middle } **Trusted API Gateways** +- :material-shield-check:{ .lg .middle } **MCP Guard** --- - Enforce trust level requirements at your API boundary. Only Level 2+ agents can access production endpoints. - -- :material-magnify:{ .lg .middle } **Agent Marketplaces** + **Tool authorization** — Protect MCP tools with trust-level requirements. - --- - - Create directories of verified agents. Users trust your curation because trust is cryptographically proven. - -- :material-shield-lock:{ .lg .middle } **Enterprise Integrations** - - --- + ```python + @guard(min_trust_level=2) + async def read_database(query: str): + pass + ``` - Meet compliance requirements with org-validated identities and audit trails. + [:octicons-arrow-right-24: MCP Guard](mcp-guard/index.md)
---- - -## Built on Standards - -CapiscIO implements and extends open standards: - -| Standard | How We Use It | -|----------|---------------| -| **[A2A Protocol](https://github.com/a2aproject/A2A)** | Agent communication format | -| **[W3C DIDs](https://www.w3.org/TR/did-core/)** | Decentralized identifiers | -| **[JWS (RFC 7515)](https://tools.ietf.org/html/rfc7515)** | Request signing | -| **[Ed25519](https://ed25519.cr.yp.to/)** | Cryptographic keys | - -We're not inventing new cryptography — we're applying proven standards to the agent economy. - -### CapiscIO RFCs - -Our core specifications are published as RFCs (Request for Comments): - -| RFC | Title | What It Defines | -|-----|-------|----------------| -| **[RFC-001](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/001-agcp.md)** | Agent Governance Control Plane (AGCP) | Authority delegation and transitive trust model | -| **[RFC-002](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/002-trust-badge.md)** | Trust Badge Specification | Cryptographic identity credentials (JWS format) | -| **[RFC-003](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/003-key-ownership-proof.md)** | Key Ownership Proof Protocol | Challenge-response key binding for IAL-1 badges | - -[:octicons-arrow-right-24: Browse All RFCs](https://github.com/capiscio/capiscio-rfcs) +[:octicons-arrow-right-24: See how these fit together](overview/index.md) --- -## Documentation - -
- -- :material-rocket-launch:{ .lg .middle } **Getting Started** - - --- - - Step-by-step guides for common tasks. - - [:octicons-arrow-right-24: Getting Started](getting-started/index.md) - -- :material-book-open:{ .lg .middle } **Concepts** - - --- - - Understand how CapiscIO works under the hood. - - [:octicons-arrow-right-24: Concepts](concepts/index.md) +## Developers Love CapiscIO -- :material-clipboard-list:{ .lg .middle } **How-To Guides** +Every feature works in **three commands or less**. - --- +=== "Validate" - Task-oriented recipes for specific problems. + ```bash + capiscio validate agent-card.json + # ✅ Validation passed: 95/100 (A+) + ``` - [:octicons-arrow-right-24: How-To Guides](how-to/index.md) +=== "Sign Requests" -- :material-api:{ .lg .middle } **Reference** + ```python + from capiscio_sdk import sign_request + signed = sign_request(request, badge) + ``` - --- +=== "Protect APIs" - Complete API documentation. + ```python + @guard.protect(min_trust_level=2) + async def handle_task(request): + pass # Only trusted agents reach here + ``` - [:octicons-arrow-right-24: Reference](reference/index.md) +=== "Guard MCP Tools" -
+ ```python + @guard(min_trust_level=3) + async def write_file(path: str, content: str): + pass # Enterprise agents only + ``` --- -## Open Source Components - -CapiscIO core tools are open source under the Apache 2.0 license. +## Quick Links
-- :fontawesome-brands-github:{ .lg .middle } **capiscio-core** +- [:material-rocket-launch: **Getting Started**](getting-started/index.md) - --- + Step-by-step tutorials to get up and running - The Go CLI and core validation engine. +- [:material-book-open: **Concepts**](concepts/index.md) - [:octicons-arrow-right-24: GitHub](https://github.com/capiscio/capiscio-core) + Understand DIDs, trust badges, and the trust model -- :material-language-python:{ .lg .middle } **capiscio-sdk** +- [:material-clipboard-list: **How-To Guides**](how-to/index.md) - --- + Task-focused recipes for common scenarios - Python SDK for runtime security. +- [:material-api: **API Reference**](reference/index.md) - [:octicons-arrow-right-24: GitHub](https://github.com/capiscio/capiscio-sdk-python) + Complete CLI, SDK, and server API documentation -- :material-server:{ .lg .middle } **capiscio-server** +- [:material-file-document: **RFCs**](rfcs/index.md) - --- - - Commercial registry and Badge CA server. + Protocol specifications and standards - [:octicons-arrow-right-24: Contact Sales](mailto:sales@capisc.io) +- [:material-help-circle: **Troubleshooting**](troubleshooting.md) -- :material-file-document:{ .lg .middle } **capiscio-docs** - - --- - - This documentation site. - - [:octicons-arrow-right-24: GitHub](https://github.com/capiscio/capiscio-docs) + Common issues and solutions
--- -## Get Started Now - -
-Generate Your DID -Sign a Badge -Validate Agent Cards +
+Questions? Open an issue · Join discussions · Get support
- -Questions? [Open an issue](https://github.com/capiscio/capiscio-core/issues) or [join the discussion](https://github.com/orgs/capiscio/discussions). diff --git a/docs/overview/index.md b/docs/overview/index.md new file mode 100644 index 0000000..00d66e5 --- /dev/null +++ b/docs/overview/index.md @@ -0,0 +1,230 @@ +# 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?"* + +- :octicons-x-circle-16: Self-descriptions can be forged +- :octicons-x-circle-16: API keys prove payment, not identity +- :octicons-x-circle-16: No standard verification mechanism + +## The Solution: Three Layers of Trust + +CapiscIO provides three products that work together: + +| Product | Phase | What It Does | +|---------|-------|--------------| +| **CapiscIO Core** | Build time | CLI for validation, key generation, badge issuance | +| **CapiscIO SDK** | Runtime | Sign requests, verify callers, enforce trust | +| **MCP Guard** | Runtime | Protect MCP tools with trust-level authorization | + +**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. + +```bash +# Validate your A2A agent card +capiscio validate agent-card.json +# ✅ Score: 95/100 (A+) + +# Generate cryptographic keys +capiscio key gen --did did:key +# ✅ did:key:z6Mk... + +# Issue a trust badge +capiscio badge issue --level 0 --self-sign +# ✅ Badge written to badge.jwt +``` + +**Use cases:** + +- CI/CD validation gates +- Pre-deployment checks +- Badge issuance pipeline +- Key management + +[:octicons-arrow-right-24: CLI Reference](../reference/cli/index.md) + +--- + +### 2. CapiscIO SDK (Python) + +**What it does:** Runtime security enforcement for your agent. + +```python +from capiscio_sdk import SimpleGuard, sign_request, verify_request + +# 1. Protect your endpoints +guard = SimpleGuard(min_trust_level=2) + +@app.post("/task") +@guard.protect +async def handle_task(request): + # Only Level 2+ agents reach here + caller = guard.get_caller_identity(request) + return await process_task(request) + +# 2. Sign your outbound requests +signed = await sign_request(request, badge=my_badge) + +# 3. Verify incoming requests +result = await verify_request(request) +if result.trust_level >= 2: + allow_access() +``` + +**Use cases:** + +- API authentication & authorization +- Request signing +- Trust level enforcement +- Audit logging + +[:octicons-arrow-right-24: Python SDK](../reference/sdk-python/index.md) + +--- + +### 3. MCP Guard + +**What it does:** Trust-level authorization for [Model Context Protocol](https://modelcontextprotocol.io) tool calls. + +```python +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 + +[:octicons-arrow-right-24: MCP Guard](../mcp-guard/index.md) + +--- + +## The Trust Flow + +Here's how trust flows through a typical interaction: + +| Step | What Happens | Code | +|:----:|--------------|------| +| **1** | Generate DID and cryptographic keypair | `capiscio key gen` | +| **2** | Registry issues trust badge (Level 0-4) | `capiscio badge issue` | +| **3** | Sign outbound requests with badge | `sign_request()` | +| **4** | Verify signature and enforce trust level | `@guard.protect` | + +--- + +## Trust Levels + +CapiscIO uses a 5-level trust hierarchy (like SSL certificates): + +| Level | Name | What's Verified | Use Case | +|:-----:|------|-----------------|----------| +| **0** | Self-Signed | Cryptographic identity only | Development, testing | +| **1** | Registered | Email verification | Personal projects | +| **2** | Domain Validated | Domain ownership (DNS) | Production APIs | +| **3** | Org Validated | Legal entity verification | Enterprise | +| **4** | Extended Validation | Enhanced due diligence | Regulated industries | + +**The key insight:** Higher levels require more verification but enable more sensitive operations. + +```python +# Development: Accept any cryptographic identity +@guard.protect(min_trust_level=0) +async def public_endpoint(): ... + +# Production: Require verified domain +@guard.protect(min_trust_level=2) +async def internal_api(): ... + +# Enterprise: Require verified organization +@guard.protect(min_trust_level=3) +async def financial_operation(): ... +``` + +--- + +## Installation Paths + +Depending on your use case: + +=== "Validate Agent Cards" + + ```bash + pip install capiscio # or: npm install -g capiscio + capiscio validate agent-card.json + ``` + +=== "Secure Python APIs" + + ```bash + pip install capiscio-sdk + ``` + + ```python + from capiscio_sdk import SimpleGuard + guard = SimpleGuard(min_trust_level=2) + ``` + +=== "Protect MCP Tools" + + ```bash + pip install capiscio-mcp + ``` + + ```python + from capiscio_mcp import guard + @guard(min_trust_level=2) + async def my_tool(): ... + ``` + +=== "CI/CD Integration" + + ```yaml + # .github/workflows/validate.yml + - uses: capiscio/validate-a2a@v2 + with: + path: agent-card.json + min-score: 80 + ``` + +--- + +## What's Next? + +
+ +- [:material-rocket-launch: **Getting Started**](../getting-started/index.md) + + Pick a tutorial based on your goal + +- [:material-book-open: **Concepts**](../concepts/index.md) + + Deep dive into DIDs, badges, and trust + +- [:material-clipboard-list: **How-To Guides**](../how-to/index.md) + + Specific recipes for common tasks + +
diff --git a/docs/reference/grpc.md b/docs/reference/grpc.md index 11294dc..3da1f91 100644 --- a/docs/reference/grpc.md +++ b/docs/reference/grpc.md @@ -12,12 +12,13 @@ ## Overview -The gRPC API provides three core services: +The gRPC API provides four core services: | Service | Description | -|---------|-------------| +|---------|-----------| | `ScoringService` | Validate and score agent cards | | `BadgeService` | Issue, verify, and manage trust badges | +| `MCPService` | MCP tool access control and server identity (RFC-006/007) | | `ValidationService` | Schema validation for agent cards | --- @@ -240,6 +241,120 @@ for event in client.start_keeper( --- +## MCPService + +Model Context Protocol security enforcement implementing RFC-006 (Tool Authority) and RFC-007 (Server Identity). + +### EvaluateToolAccess + +Evaluate whether a caller is authorized to invoke an MCP tool. + +```protobuf +rpc EvaluateToolAccess(EvaluateToolAccessRequest) returns (EvaluateToolAccessResponse); +``` + +**Request:** + +```python +result = client.mcp.evaluate_tool_access( + tool_name="write_file", + params_hash="sha256:abc123...", + server_origin="https://files.example.com", + badge_jws=caller_badge, + min_trust_level=2, # Require OV + trusted_issuers=["https://registry.capisc.io"], +) +``` + +**Response:** + +```json +{ + "decision": "allow", + "agent_did": "did:web:example.com:agents:alice", + "auth_level": "badge", + "trust_level": 2, + "evidence_id": "ev_abc123", + "timestamp": "2025-01-15T12:00:00Z" +} +``` + +### VerifyServerIdentity + +Verify an MCP server's identity before trusting responses. + +```protobuf +rpc VerifyServerIdentity(VerifyServerIdentityRequest) returns (VerifyServerIdentityResponse); +``` + +**Request:** + +```python +result = client.mcp.verify_server_identity( + server_did="did:web:files.example.com:mcp:files", + server_badge=server_badge_token, + transport_origin="https://files.example.com", + min_trust_level=1, +) +``` + +**Response:** + +```json +{ + "state": "verified_principal", + "trust_level": 2, + "server_did": "did:web:files.example.com:mcp:files", + "badge_jti": "badge_xyz789" +} +``` + +### ParseServerIdentity + +Extract server identity from HTTP headers or JSON-RPC `_meta`. + +```protobuf +rpc ParseServerIdentity(ParseServerIdentityRequest) returns (ParseServerIdentityResponse); +``` + +**HTTP Headers:** + +```python +identity = client.mcp.parse_server_identity_http( + capiscio_server_did=response.headers.get("Capiscio-Server-DID", ""), + capiscio_server_badge=response.headers.get("Capiscio-Server-Badge", ""), +) +``` + +**JSON-RPC `_meta`:** + +```python +identity = client.mcp.parse_server_identity_jsonrpc( + meta_json=json.dumps(response.get("_meta", {})) +) +``` + +### Server States + +| State | Description | Action | +|-------|-------------|--------| +| `verified_principal` | DID verified, badge valid, origin matches | Trust responses | +| `declared_principal` | DID provided but not fully verified | Prompt user | +| `unverified_origin` | Origin doesn't match DID | Reject or warn | + +### Deny Reasons + +| Reason | Description | +|--------|-------------| +| `badge_missing` | No credential provided | +| `badge_invalid` | Signature verification failed | +| `badge_expired` | Badge has expired | +| `trust_insufficient` | Trust level below minimum | +| `tool_not_allowed` | Tool not in allowlist | +| `issuer_untrusted` | Badge issuer not trusted | + +--- + ## Trust Levels The `TrustLevel` enum maps to badge trust levels: @@ -262,6 +377,7 @@ The protobuf definitions are located at: ``` capiscio-core/proto/capiscio/v1/ ├── badge.proto # BadgeService +├── mcp.proto # MCPService (RFC-006/007) ├── scoring.proto # ScoringService ├── common.proto # Shared types ├── did.proto # DID operations @@ -318,5 +434,8 @@ except RpcError as e: - [CLI Reference](cli/index.md) — Command-line interface - [Python SDK](sdk-python/index.md) — `CapiscioRPCClient` wrapper +- [MCP API](sdk-python/mcp.md) — MCP tool access control - [Badge CA](server/badge-ca.md) — CA operations - [RFC-002: Trust Badge](https://docs.capisc.io/rfcs/blob/main/docs/002-trust-badge.md) — Badge specification +- [RFC-006: MCP Tool Authority](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/006-mcp-tool-authority.md) — Tool access spec +- [RFC-007: MCP Server Identity](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/007-mcp-server-identity.md) — Server identity spec diff --git a/docs/reference/index.md b/docs/reference/index.md index 553ae77..ecc1c27 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -1,42 +1,58 @@ # API Reference -Complete reference documentation for all CapiscIO APIs, CLIs, and configuration options. +Complete reference documentation for all CapiscIO products. -## Quick Links +## Products
-- :material-console:{ .lg .middle } **CLI Reference** +- :material-console:{ .lg .middle } **CapiscIO Core** --- - Command-line interface for validation, key management, badges, and gateway. + CLI and Go library for validation, key management, and badge operations. - [:octicons-arrow-right-24: CLI Commands](cli/index.md) + - [CLI Reference](cli/index.md) + - [Go API](go-api.md) + - [gRPC Services](grpc.md) -- :material-language-python:{ .lg .middle } **Python SDK** +- :material-language-python:{ .lg .middle } **CapiscIO SDK** --- - Security middleware for Python applications with SimpleGuard and Executor. + Python SDK for runtime security—signing, verification, and trust enforcement. - [:octicons-arrow-right-24: SDK Reference](sdk-python/index.md) + - [Overview](sdk-python/index.md) + - [SimpleGuard](sdk-python/simple-guard.md) + - [Badge](sdk-python/badge.md) + - [Types](sdk-python/types.md) -- :material-server:{ .lg .middle } **Server API** +- :material-shield-check:{ .lg .middle } **MCP Guard** --- - capiscio-server REST API for agent registry and badge CA operations. + Tool-level authorization for Model Context Protocol servers. - [:octicons-arrow-right-24: Server Reference](server/index.md) + - [MCP Guard Reference](../mcp-guard/api-reference.md) + - [Guard Config](sdk-python/mcp.md) -- :material-api:{ .lg .middle } **gRPC Services** +- :material-server:{ .lg .middle } **Server API** --- - gRPC API for validation, scoring, and badge operations. + capiscio-server REST API for agent registry and badge CA. + + - [Server Reference](server/index.md) + - [Badge CA](server/badge-ca.md) + - [Deployment](server/deployment.md) + +
+ +--- + +## Quick Reference - [:octicons-arrow-right-24: gRPC Reference](grpc.md) +
- :material-cog:{ .lg .middle } **Configuration** @@ -54,28 +70,39 @@ Complete reference documentation for all CapiscIO APIs, CLIs, and configuration [:octicons-arrow-right-24: Schema Reference](agent-card-schema.md) +- :material-download:{ .lg .middle } **Installation** + + --- + + Package installation across all platforms and package managers. + + [:octicons-arrow-right-24: Installation Options](wrappers/index.md) +
--- ## Package Installation -=== "npm" +=== "CapiscIO Core (CLI)" ```bash - npm install capiscio + npm install -g capiscio # Node.js wrapper + # or + pip install capiscio # Python wrapper ``` -=== "pip" +=== "CapiscIO SDK" ```bash - pip install capiscio + pip install capiscio-sdk ``` -=== "pip (SDK)" +=== "MCP Guard" ```bash - pip install capiscio-sdk + pip install capiscio-mcp # Standalone + pip install capiscio-mcp[mcp] # With MCP SDK integration ``` === "Docker" @@ -88,10 +115,11 @@ Complete reference documentation for all CapiscIO APIs, CLIs, and configuration ## Version Compatibility -| Package | Version | Node.js | Python | Go | -|---------|---------|---------|--------|----| -| `capiscio` (npm) | 1.0.x | ≥18.0 | - | - | -| `capiscio` (pip) | 1.0.x | - | ≥3.10 | - | -| `capiscio-sdk` | 0.3.x | - | ≥3.10 | - | -| `capiscio-core` | 1.0.x | - | - | ≥1.21 | +| Package | Version | Platform | Requirements | +|---------|---------|----------|--------------| +| `capiscio` (npm) | 2.x | Node.js | ≥18.0 | +| `capiscio` (pip) | 2.x | Python | ≥3.10 | +| `capiscio-sdk` | 0.3.x | Python | ≥3.10 | +| `capiscio-mcp` | 0.1.x | Python | ≥3.10 | +| `capiscio-core` (Go) | 2.x | Go | ≥1.21 | diff --git a/docs/reference/sdk-python/index.md b/docs/reference/sdk-python/index.md index 9a133a4..1f867da 100644 --- a/docs/reference/sdk-python/index.md +++ b/docs/reference/sdk-python/index.md @@ -58,6 +58,10 @@ from capiscio_sdk.errors import ( # Types from capiscio_sdk import ValidationResult, ValidationIssue, ValidationSeverity + +# MCP API (Model Context Protocol security) +from capiscio_sdk._rpc.client import CapiscioRPCClient +# Access MCP via: client.mcp.evaluate_tool_access(...) ``` --- @@ -119,6 +123,15 @@ from capiscio_sdk import ValidationResult, ValidationIssue, ValidationSeverity [:octicons-arrow-right-24: Types API](types.md) +- :material-server-security: **MCP API** + + --- + + Model Context Protocol security enforcement. Tool access control + (RFC-006) and server identity verification (RFC-007). + + [:octicons-arrow-right-24: MCP API](mcp.md) +
--- diff --git a/docs/reference/sdk-python/mcp.md b/docs/reference/sdk-python/mcp.md new file mode 100644 index 0000000..2513bc4 --- /dev/null +++ b/docs/reference/sdk-python/mcp.md @@ -0,0 +1,553 @@ +--- +title: MCP API +description: Model Context Protocol security enforcement for AI tool access control +--- + +# MCP API + +The MCP API provides security enforcement for Model Context Protocol servers and clients, implementing RFC-006 (Tool Authority) and RFC-007 (Server Identity). + +!!! info "RFC Implementation" + This API implements RFC-006: MCP Tool Authority (agent access control) and RFC-007: MCP Server Identity (server verification). + +--- + +## Quick Start + +```python +from capiscio_sdk._rpc.client import CapiscioRPCClient + +# Connect to capiscio-core +client = CapiscioRPCClient() +client.connect() + +# Evaluate tool access for an incoming request +result = client.mcp.evaluate_tool_access( + tool_name="write_file", + badge_jws=incoming_badge, + server_origin="https://files.example.com", + min_trust_level=1, # Require at least DV +) + +if result["decision"] == "allow": + print(f"✅ Access granted for agent {result['agent_did']}") +else: + print(f"❌ Access denied: {result['deny_reason']}") +``` + +--- + +## Access Pattern + +The `MCPClient` is accessed via the `CapiscioRPCClient.mcp` property: + +```python +from capiscio_sdk._rpc.client import CapiscioRPCClient + +client = CapiscioRPCClient() +client.connect() + +# Access MCP client +mcp = client.mcp + +# Now use MCP methods +result = mcp.evaluate_tool_access(tool_name="read_file") +``` + +--- + +## Functions + +### evaluate_tool_access + +Evaluate whether a caller is authorized to invoke an MCP tool (RFC-006 §6.2-6.4). + +```python +def evaluate_tool_access( + tool_name: str, + params_hash: str = "", + server_origin: str = "", + *, + badge_jws: Optional[str] = None, + api_key: Optional[str] = None, + policy_version: str = "", + trusted_issuers: Optional[list[str]] = None, + min_trust_level: int = 0, + accept_level_zero: bool = False, + allowed_tools: Optional[list[str]] = None, +) -> dict +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `tool_name` | `str` | Name of the MCP tool being invoked | +| `params_hash` | `str` | SHA-256 hash of tool parameters (for audit trail) | +| `server_origin` | `str` | Origin of the MCP server (e.g., `https://files.example.com`) | +| `badge_jws` | `str` | Caller's Trust Badge JWT for badge-based auth | +| `api_key` | `str` | Caller's API key for key-based auth | +| `policy_version` | `str` | Optional policy version to apply | +| `trusted_issuers` | `list[str]` | List of trusted badge issuer URLs | +| `min_trust_level` | `int` | Minimum required trust level (0-4) | +| `accept_level_zero` | `bool` | Accept self-signed (Level 0) badges | +| `allowed_tools` | `list[str]` | Explicit allowlist of tool names | + +**Returns:** `dict` with evaluation result: + +| Key | Type | Description | +|-----|------|-------------| +| `decision` | `str` | `"allow"` or `"deny"` | +| `deny_reason` | `str` | Reason code if denied (see table below) | +| `deny_detail` | `str` | Human-readable error message | +| `agent_did` | `str` | Authenticated agent's DID | +| `badge_jti` | `str` | Badge unique identifier | +| `auth_level` | `str` | `"anonymous"`, `"api_key"`, or `"badge"` | +| `trust_level` | `int` | Agent's trust level (0-4) | +| `evidence_json` | `str` | RFC-006 §7 evidence record | +| `evidence_id` | `str` | Unique evidence record ID | +| `timestamp` | `str` | Evaluation timestamp (ISO 8601) | + +**Deny Reasons:** + +| Code | Description | +|------|-------------| +| `badge_missing` | No badge or API key provided | +| `badge_invalid` | Badge signature verification failed | +| `badge_expired` | Badge has expired | +| `badge_revoked` | Badge has been revoked | +| `trust_insufficient` | Trust level below minimum | +| `tool_not_allowed` | Tool not in allowed list | +| `issuer_untrusted` | Badge issuer not trusted | +| `policy_denied` | Policy explicitly denied access | + +**Example:** + +```python +import hashlib +import json + +# Evaluate with badge authentication +result = client.mcp.evaluate_tool_access( + tool_name="write_file", + params_hash=hashlib.sha256(json.dumps({"path": "/tmp/test.txt"}).encode()).hexdigest(), + server_origin="https://files.example.com", + badge_jws=badge_token, + min_trust_level=2, # Require OV or higher + trusted_issuers=["https://registry.capisc.io"], +) + +if result["decision"] == "allow": + # Proceed with tool execution + execute_tool(tool_name, params) +else: + raise PermissionError(f"{result['deny_reason']}: {result['deny_detail']}") +``` + +--- + +### verify_server_identity + +Verify an MCP server's identity before trusting its responses (RFC-007 §7.2). + +```python +def verify_server_identity( + server_did: str, + server_badge: str = "", + transport_origin: str = "", + endpoint_path: str = "", + *, + trusted_issuers: Optional[list[str]] = None, + min_trust_level: int = 0, + accept_level_zero: bool = False, + offline_mode: bool = False, + skip_origin_binding: bool = False, +) -> dict +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `server_did` | `str` | Server's DID (`did:web:...` or `did:key:...`) | +| `server_badge` | `str` | Server's Trust Badge JWT (optional for Level 0) | +| `transport_origin` | `str` | Origin from transport (e.g., `https://files.example.com`) | +| `endpoint_path` | `str` | Endpoint path being accessed | +| `trusted_issuers` | `list[str]` | Trusted badge issuer URLs | +| `min_trust_level` | `int` | Minimum required trust level (0-4) | +| `accept_level_zero` | `bool` | Accept self-signed servers | +| `offline_mode` | `bool` | Use cache only, skip online checks | +| `skip_origin_binding` | `bool` | Skip RFC-007 §5.3 origin binding check | + +**Returns:** `dict` with verification result: + +| Key | Type | Description | +|-----|------|-------------| +| `state` | `str` | Server state (see table below) | +| `trust_level` | `int` | Server's trust level (0-4) | +| `server_did` | `str` | Verified server DID | +| `badge_jti` | `str` | Server badge identifier | +| `error_code` | `str` | Error code if verification failed | +| `error_detail` | `str` | Human-readable error message | + +**Server States (RFC-007 §7.3):** + +| State | Description | Trust | +|-------|-------------|-------| +| `verified_principal` | DID verified, badge valid, origin matches | High | +| `declared_principal` | DID provided but not fully verified | Medium | +| `unverified_origin` | Origin doesn't match DID or badge | Low | + +**Error Codes:** + +| Code | Description | +|------|-------------| +| `did_invalid` | Invalid DID format | +| `badge_invalid` | Badge signature verification failed | +| `badge_expired` | Server badge has expired | +| `badge_revoked` | Server badge has been revoked | +| `trust_insufficient` | Trust level below minimum | +| `origin_mismatch` | Transport origin doesn't match DID | +| `path_mismatch` | Endpoint path doesn't match badge scope | +| `issuer_untrusted` | Badge issuer not trusted | + +**Example:** + +```python +# Verify server before trusting tool results +result = client.mcp.verify_server_identity( + server_did="did:web:files.example.com:mcp:files", + server_badge=server_badge_token, + transport_origin="https://files.example.com", + min_trust_level=1, # Require at least DV +) + +if result["state"] == "verified_principal": + print(f"✅ Server verified at trust level {result['trust_level']}") + # Trust the server's responses +else: + print(f"⚠️ Server not fully verified: {result['error_detail']}") + # Prompt user for confirmation or reject +``` + +--- + +### parse_server_identity_http + +Extract server identity from HTTP response headers (RFC-007 §5.2). + +```python +def parse_server_identity_http( + capiscio_server_did: str = "", + capiscio_server_badge: str = "", +) -> dict +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `capiscio_server_did` | `str` | Value of `Capiscio-Server-DID` header | +| `capiscio_server_badge` | `str` | Value of `Capiscio-Server-Badge` header | + +**Returns:** `dict`: + +| Key | Type | Description | +|-----|------|-------------| +| `server_did` | `str` | Extracted server DID | +| `server_badge` | `str` | Extracted server badge JWT | +| `identity_present` | `bool` | Whether identity headers were present | + +**Example:** + +```python +import requests + +# Make request to MCP server +response = requests.post("https://files.example.com/mcp/tools/read_file", ...) + +# Parse identity from response headers +identity = client.mcp.parse_server_identity_http( + capiscio_server_did=response.headers.get("Capiscio-Server-DID", ""), + capiscio_server_badge=response.headers.get("Capiscio-Server-Badge", ""), +) + +if identity["identity_present"]: + # Verify the server identity + verification = client.mcp.verify_server_identity( + server_did=identity["server_did"], + server_badge=identity["server_badge"], + transport_origin="https://files.example.com", + ) +``` + +--- + +### parse_server_identity_jsonrpc + +Extract server identity from JSON-RPC `_meta` field (RFC-007 §5.3). + +```python +def parse_server_identity_jsonrpc(meta_json: str) -> dict +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `meta_json` | `str` | JSON string of the `_meta` object | + +**Returns:** `dict`: + +| Key | Type | Description | +|-----|------|-------------| +| `server_did` | `str` | Extracted server DID | +| `server_badge` | `str` | Extracted server badge JWT | +| `identity_present` | `bool` | Whether identity was present in `_meta` | + +**Example:** + +```python +import json + +# JSON-RPC response from stdio MCP server +response = { + "jsonrpc": "2.0", + "id": 1, + "result": {"content": "..."}, + "_meta": { + "serverDid": "did:web:files.example.com:mcp:files", + "serverBadge": "eyJhbGciOiJFZERTQSI..." + } +} + +# Parse identity from _meta +identity = client.mcp.parse_server_identity_jsonrpc( + meta_json=json.dumps(response.get("_meta", {})) +) + +if identity["identity_present"]: + # Verify the server + verification = client.mcp.verify_server_identity( + server_did=identity["server_did"], + server_badge=identity["server_badge"], + ) +``` + +--- + +### health + +Check MCP service health and version compatibility. + +```python +def health(client_version: str = "") -> dict +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `client_version` | `str` | Client version for compatibility check | + +**Returns:** `dict`: + +| Key | Type | Description | +|-----|------|-------------| +| `healthy` | `bool` | Whether service is healthy | +| `core_version` | `str` | capiscio-core version | +| `proto_version` | `str` | Protocol buffer version | +| `version_compatible` | `bool` | Whether versions are compatible | + +**Example:** + +```python +status = client.mcp.health(client_version="capiscio-sdk-python/2.5.0") + +if status["healthy"]: + print(f"✅ MCP service healthy (core {status['core_version']})") +else: + print("❌ MCP service unhealthy") +``` + +--- + +## Trust Levels + +MCP enforces CapiscIO trust levels (RFC-002): + +| Level | Name | Description | Use Case | +|-------|------|-------------|----------| +| **0** | Self-Signed | `did:key` only, no CA | Development, testing | +| **1** | Registered | Account verified by CA | Internal tools | +| **2** | Domain Validated (DV) | DNS/HTTP challenge | Production B2B | +| **3** | Organization Validated (OV) | Legal entity verified | High-trust ops | +| **4** | Extended Validated (EV) | Security audit completed | Regulated industries | + +```python +# Require different trust levels for different tools +sensitive_tools = ["execute_shell", "delete_file", "modify_system"] + +if tool_name in sensitive_tools: + min_level = 3 # Require OV for dangerous tools +else: + min_level = 1 # DV sufficient for normal tools + +result = client.mcp.evaluate_tool_access( + tool_name=tool_name, + badge_jws=badge, + min_trust_level=min_level, +) +``` + +--- + +## Patterns + +### MCP Server Middleware (FastAPI + SSE) + +```python +from fastapi import FastAPI, Request, HTTPException +from capiscio_sdk._rpc.client import CapiscioRPCClient + +app = FastAPI() +client = CapiscioRPCClient() +client.connect() + +@app.middleware("http") +async def mcp_auth(request: Request, call_next): + # Skip auth for health/docs + if request.url.path in ["/health", "/docs", "/openapi.json"]: + return await call_next(request) + + # Extract badge from Authorization header + auth = request.headers.get("Authorization", "") + if not auth.startswith("Bearer "): + raise HTTPException(401, "Missing badge token") + + badge = auth[7:] + + # Extract tool name from path (e.g., /tools/read_file) + tool_name = request.url.path.split("/")[-1] + + # Evaluate access + result = client.mcp.evaluate_tool_access( + tool_name=tool_name, + badge_jws=badge, + server_origin=str(request.base_url).rstrip("/"), + min_trust_level=1, + trusted_issuers=["https://registry.capisc.io"], + ) + + if result["decision"] != "allow": + raise HTTPException( + 403, + detail={ + "error": "access_denied", + "reason": result["deny_reason"], + "detail": result["deny_detail"], + } + ) + + # Attach agent info to request + request.state.agent_did = result["agent_did"] + request.state.trust_level = result["trust_level"] + + return await call_next(request) +``` + +### MCP Client Verification + +```python +from capiscio_sdk._rpc.client import CapiscioRPCClient +import requests + +client = CapiscioRPCClient() +client.connect() + +def call_mcp_tool(server_url: str, tool_name: str, params: dict) -> dict: + """Call an MCP tool with server identity verification.""" + + # Make the tool call + response = requests.post( + f"{server_url}/tools/{tool_name}", + json=params, + headers={"Authorization": f"Bearer {my_badge}"}, + ) + + # Parse and verify server identity + identity = client.mcp.parse_server_identity_http( + capiscio_server_did=response.headers.get("Capiscio-Server-DID", ""), + capiscio_server_badge=response.headers.get("Capiscio-Server-Badge", ""), + ) + + if not identity["identity_present"]: + raise ValueError("Server did not provide identity headers") + + verification = client.mcp.verify_server_identity( + server_did=identity["server_did"], + server_badge=identity["server_badge"], + transport_origin=server_url, + min_trust_level=1, + ) + + if verification["state"] != "verified_principal": + raise ValueError(f"Server verification failed: {verification['error_detail']}") + + return response.json() +``` + +### Tool Allowlist Enforcement + +```python +# Define allowed tools per trust level +TOOL_ALLOWLIST = { + 0: ["read_file", "list_directory"], # Level 0: read-only + 1: ["read_file", "list_directory", "search"], # Level 1: + search + 2: ["read_file", "list_directory", "search", "write_file"], # Level 2: + write + 3: ["read_file", "list_directory", "search", "write_file", "execute"], # Level 3: + execute +} + +def get_allowed_tools(trust_level: int) -> list[str]: + """Get allowed tools for a trust level.""" + return TOOL_ALLOWLIST.get(trust_level, TOOL_ALLOWLIST[0]) + +# Use in evaluation +result = client.mcp.evaluate_tool_access( + tool_name=requested_tool, + badge_jws=badge, + allowed_tools=get_allowed_tools(caller_trust_level), +) +``` + +--- + +## Error Handling + +```python +from grpc import RpcError, StatusCode + +try: + result = client.mcp.evaluate_tool_access( + tool_name="write_file", + badge_jws=badge, + ) +except RpcError as e: + if e.code() == StatusCode.UNAVAILABLE: + print("MCP service unavailable - check capiscio-core is running") + elif e.code() == StatusCode.INVALID_ARGUMENT: + print(f"Invalid request: {e.details()}") + else: + raise +``` + +--- + +## See Also + +- [gRPC Services: MCPService](../grpc.md#mcpservice) — Low-level gRPC API +- [Trust Badges](../../how-to/security/badges.md) — Badge issuance and verification +- [Trust Model](../../concepts/trust-model.md) — Trust levels explained +- [Server Registration](../../mcp-guard/guides/server-registration.md) — MCP Guard server identity registration +- [RFC-006: MCP Tool Authority](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/006-mcp-tool-authority.md) — Specification +- [RFC-007: MCP Server Identity](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/007-mcp-server-identity.md) — Specification diff --git a/mkdocs.yml b/mkdocs.yml index 84a6186..cd379de 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -78,7 +78,7 @@ plugins: default_handler: python handlers: python: - paths: ["../capiscio-sdk-python"] + paths: ["../capiscio-sdk-python", "../capiscio-mcp-python"] import: # Enable cross-references to Python stdlib and pydantic - https://docs.python.org/3/objects.inv @@ -157,6 +157,7 @@ extra_css: nav: - Home: index.md + - Overview: overview/index.md - Getting Started: - getting-started/index.md @@ -172,6 +173,9 @@ nav: - getting-started/secure/3-guard.md - getting-started/secure/4-test.md - getting-started/secure/5-production.md + - Protect MCP Tools: + - mcp-guard/getting-started/installation.md + - mcp-guard/getting-started/quickstart.md - CI/CD Integration: - getting-started/cicd/1-intro.md - getting-started/cicd/2-action.md @@ -184,11 +188,14 @@ nav: - concepts/index.md - Identity & DIDs: identity/index.md - Trust Badges: trust/index.md + - Trust Levels: concepts/trust-model.md - Agent Registry: registry/index.md - - Validation Process: concepts/validation.md - - Scoring System: concepts/scoring.md - - Trust Model: concepts/trust-model.md + - Validation & Scoring: + - concepts/validation.md + - concepts/scoring.md - Enforcement: concepts/enforcement.md + - MCP Security: + - Overview: concepts/mcp-security.md - How-To Guides: - how-to/index.md @@ -207,6 +214,12 @@ nav: - Dev Mode: how-to/security/dev-mode.md - Key Rotation: how-to/security/key-rotation.md - Trust Store: how-to/security/trust-store.md + - MCP Security: + - Protect MCP Tools: mcp-guard/guides/server-side.md + - Verify MCP Servers: mcp-guard/guides/client-side.md + - Server Registration: mcp-guard/guides/server-registration.md + - Evidence Logging: mcp-guard/guides/evidence.md + - MCP SDK Integration: mcp-guard/guides/mcp-integration.md - Integrations: - FastAPI: how-to/integrations/fastapi.md - Flask: how-to/integrations/flask.md @@ -221,22 +234,25 @@ nav: - Reference: - reference/index.md - - CLI Reference: reference/cli/index.md - - gRPC Services: reference/grpc.md - - Python SDK: + - CapiscIO Core: + - CLI Reference: reference/cli/index.md + - Go API: reference/go-api.md + - gRPC Services: reference/grpc.md + - CapiscIO SDK: - reference/sdk-python/index.md - Badge: reference/sdk-python/badge.md - SecurityConfig: reference/sdk-python/config.md - CapiscioSecurityExecutor: reference/sdk-python/executor.md - SimpleGuard: reference/sdk-python/simple-guard.md + - MCP: reference/sdk-python/mcp.md - Types: reference/sdk-python/types.md - Errors: reference/sdk-python/errors.md + - MCP Guard: '!include ../capiscio-mcp-python/mkdocs.yml' - Server API: - reference/server/index.md - API Reference: reference/server/api.md - Deployment: reference/server/deployment.md - Badge CA: reference/server/badge-ca.md - - Go API: reference/go-api.md - Configuration: reference/configuration.md - Agent Card Schema: reference/agent-card-schema.md - Installation: