Skip to content

Commit 87ea82f

Browse files
beondebeonde
authored
docs: Integrate MCP Guard content into main documentation (#15)
* docs: integrate MCP Guard content into main docs - Add MCP Security concepts page (concepts/mcp-security.md) - Add How CapiscIO Works overview page (overview/index.md) - Add MCP Guard Python SDK reference (reference/sdk-python/mcp.md) - Update homepage with MCP Guard featured product - Update navigation with MCP Guard sections - Add MCPService to gRPC reference - Update getting-started, how-to, and reference indexes * fix: add missing capiscio-mcp-python checkout to CI The mkdocs.yml includes capiscio-mcp-python for MCP Guard reference docs, but the CI workflow was missing the checkout step for this repo. * fix: use external GitHub URLs for RFC-006 and RFC-007 links The monorepo plugin doesn't properly resolve relative RFC paths. Use direct GitHub links for consistency with other RFC references. * ci: temporarily use fix/rfc-links branch for capiscio-mcp-python
1 parent ba255dd commit 87ea82f

12 files changed

Lines changed: 1322 additions & 353 deletions

File tree

‎.github/workflows/deploy.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,15 @@ jobs:
8888
path: capiscio-rfcs
8989
fetch-depth: 0
9090
token: ${{ secrets.GITHUB_TOKEN }}
91+
92+
- name: Checkout capiscio-mcp-python
93+
uses: actions/checkout@v4
94+
with:
95+
repository: capiscio/capiscio-mcp-python
96+
path: capiscio-mcp-python
97+
ref: fix/rfc-links # TODO: Remove after capiscio/capiscio-mcp-python#4 is merged
98+
fetch-depth: 0
99+
token: ${{ secrets.GITHUB_TOKEN }}
91100

92101
- name: Set up Python
93102
uses: actions/setup-python@v5

‎docs/concepts/index.md‎

Lines changed: 64 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,39 @@ Understand how CapiscIO works under the hood. These docs explain the **why** and
99

1010
---
1111

12-
## Core Concepts
12+
## Identity & Trust
13+
14+
<div class="grid cards" markdown>
15+
16+
- :material-identifier:{ .lg .middle } **Identity & DIDs**
17+
18+
---
19+
20+
Decentralized identifiers give your agent a permanent, cryptographically verifiable identity.
21+
22+
[:octicons-arrow-right-24: Learn about DIDs](../identity/index.md)
23+
24+
- :material-certificate:{ .lg .middle } **Trust Badges**
25+
26+
---
27+
28+
Cryptographic credentials that attest to your agent's identity verification level (0-4).
29+
30+
[:octicons-arrow-right-24: Understanding Badges](../trust/index.md)
31+
32+
- :material-key:{ .lg .middle } **Trust Levels**
33+
34+
---
35+
36+
The five-level verification hierarchy—from self-signed to extended validation.
37+
38+
[:octicons-arrow-right-24: Trust Levels](trust-model.md)
39+
40+
</div>
41+
42+
---
43+
44+
## Validation & Scoring
1345

1446
<div class="grid cards" markdown>
1547

@@ -29,13 +61,13 @@ Understand how CapiscIO works under the hood. These docs explain the **why** and
2961

3062
[:octicons-arrow-right-24: Understanding Scores](scoring.md)
3163

32-
- :material-key:{ .lg .middle } **Trust Model**
64+
</div>
3365

34-
---
66+
---
3567

36-
How Ed25519 keys, trust stores, and cryptographic verification work. The SSH-like model explained.
68+
## Runtime Security
3769

38-
[:octicons-arrow-right-24: Trust Model](trust-model.md)
70+
<div class="grid cards" markdown>
3971

4072
- :material-shield-check:{ .lg .middle } **Enforcement**
4173

@@ -45,6 +77,30 @@ Understand how CapiscIO works under the hood. These docs explain the **why** and
4577

4678
[:octicons-arrow-right-24: Enforcement](enforcement.md)
4779

80+
- :material-tools:{ .lg .middle } **MCP Security**
81+
82+
---
83+
84+
RFC-006 (tool authorization) and RFC-007 (server verification) for Model Context Protocol.
85+
86+
[:octicons-arrow-right-24: MCP Security](mcp-security.md)
87+
88+
</div>
89+
90+
---
91+
92+
## Infrastructure
93+
94+
<div class="grid cards" markdown>
95+
96+
- :material-server:{ .lg .middle } **Agent Registry**
97+
98+
---
99+
100+
The central registry for agent discovery, DID resolution, and badge verification.
101+
102+
[:octicons-arrow-right-24: Registry](../registry/index.md)
103+
48104
</div>
49105

50106
---
@@ -91,6 +147,7 @@ Understand how CapiscIO works under the hood. These docs explain the **why** and
91147
| **[Scoring](scoring.md)** | "How good is this agent across compliance, trust, availability?" |
92148
| **[Trust Model](trust-model.md)** | "How do I manage who my agent trusts?" |
93149
| **[Enforcement](enforcement.md)** | "How do I protect my agent at runtime?" |
150+
| **[MCP Guard](../mcp-guard/index.md)** | "How do I secure MCP tools?" |
94151

95152
---
96153

@@ -103,6 +160,8 @@ For the formal technical specifications, see the CapiscIO RFCs:
103160
| **[RFC-001](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/001-agcp.md)** | Agent Governance Control Plane (AGCP) | ✅ Approved |
104161
| **[RFC-002](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/002-trust-badge.md)** | Trust Badge Specification | ✅ Approved |
105162
| **[RFC-003](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/003-key-ownership-proof.md)** | Key Ownership Proof Protocol | ✅ Approved |
163+
| **[RFC-006](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/006-mcp-tool-authority-evidence.md)** | MCP Tool Authority Evidence | ✅ Approved |
164+
| **[RFC-007](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/007-mcp-server-identity-discovery.md)** | MCP Server Identity Discovery | ✅ Approved |
106165

107166
[:octicons-arrow-right-24: Browse All RFCs](https://github.com/capiscio/capiscio-rfcs){ .md-button }
108167

‎docs/concepts/mcp-security.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# MCP Security
2+
3+
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.
4+
5+
## The Problem
6+
7+
MCP servers expose powerful tools to autonomous agents—file systems, databases, APIs, code execution. But MCP itself doesn't define:
8+
9+
- **Who** is calling a tool (authentication)
10+
- **Whether** they should have access (authorization)
11+
- **What** happened for post-incident review (audit)
12+
13+
## The Solution: Two RFCs
14+
15+
MCP Guard implements two CapiscIO specifications:
16+
17+
### RFC-006: MCP Tool Authority and Evidence
18+
19+
**Server-side protection.** Define trust level requirements for individual tools.
20+
21+
```python
22+
from capiscio_mcp import guard
23+
24+
@guard(min_trust_level=2)
25+
async def read_database(query: str) -> list[dict]:
26+
"""Only Level 2+ agents can query the database."""
27+
return await db.execute(query)
28+
29+
@guard(min_trust_level=3)
30+
async def write_database(table: str, data: dict):
31+
"""Only Level 3+ (org-validated) agents can write."""
32+
return await db.insert(table, data)
33+
```
34+
35+
**Key features:**
36+
37+
- **Trust level enforcement** — Require minimum verification level
38+
- **Evidence logging** — Cryptographic audit trail for every call
39+
- **Parameter hashing** — PII-safe evidence records
40+
- **Async and sync** — Both decorator styles supported
41+
42+
[:octicons-arrow-right-24: RFC-006 Full Specification](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/006-mcp-tool-authority-evidence.md)
43+
44+
---
45+
46+
### RFC-007: MCP Server Identity Disclosure
47+
48+
**Client-side verification.** Verify MCP server identity before connecting.
49+
50+
```python
51+
from capiscio_mcp import verify_server, ServerState
52+
53+
result = await verify_server(
54+
server_did="did:web:mcp.example.com",
55+
server_badge="eyJhbGc...",
56+
transport_origin="https://mcp.example.com",
57+
)
58+
59+
if result.state == ServerState.VERIFIED_PRINCIPAL:
60+
print(f"✓ Trusted server at Level {result.trust_level}")
61+
else:
62+
print("⚠ Server identity not verified")
63+
```
64+
65+
**Key features:**
66+
67+
- **Server identity verification** — Confirm who you're connecting to
68+
- **Transport binding** — Verify server controls the transport endpoint
69+
- **Trust level inspection** — Check server's verification level
70+
- **Three states** — VERIFIED_PRINCIPAL, DECLARED_PRINCIPAL, UNVERIFIED_ORIGIN
71+
72+
[:octicons-arrow-right-24: RFC-007 Full Specification](https://github.com/capiscio/capiscio-rfcs/blob/main/docs/007-mcp-server-identity-discovery.md)
73+
74+
---
75+
76+
## How They Work Together
77+
78+
```
79+
┌─────────────────────────────────────────────────────────────────┐
80+
│ MCP Security Flow │
81+
├─────────────────────────────────────────────────────────────────┤
82+
│ │
83+
│ MCP CLIENT MCP SERVER │
84+
│ ┌─────────────┐ ┌─────────────┐ │
85+
│ │ Agent A │ │ File Tool │ │
86+
│ │ (Level 2) │ │ Server │ │
87+
│ └─────────────┘ └─────────────┘ │
88+
│ │ │ │
89+
│ │ 1. Verify server identity │ │
90+
│ │ (RFC-007) │ │
91+
│ │ ─────────────────────────────────────>│ │
92+
│ │ │ │
93+
│ │ 2. Call tool with badge │ │
94+
│ │ ─────────────────────────────────────>│ │
95+
│ │ │ │
96+
│ │ 3. Guard evaluates │ │
97+
│ │ (RFC-006) │ │
98+
│ │ ▼ │
99+
│ │ ┌─────────────┐ │
100+
│ │ │ @guard(2) │ │
101+
│ │ │ → ALLOW │ │
102+
│ │ │ → log audit │ │
103+
│ │ └─────────────┘ │
104+
│ │ │ │
105+
│ │ 4. Return result │ │
106+
│ │ <─────────────────────────────────────│ │
107+
│ │
108+
└─────────────────────────────────────────────────────────────────┘
109+
```
110+
111+
1. **Client verifies server** using RFC-007 before connecting
112+
2. **Client calls tool** with their trust badge attached
113+
3. **Server guard evaluates** the caller's trust level (RFC-006)
114+
4. **Evidence logged** regardless of allow/deny decision
115+
116+
---
117+
118+
## Trust Levels in MCP Context
119+
120+
| Level | Server Use | Client Use |
121+
|:-----:|------------|------------|
122+
| **0** | Development servers | Anonymous tool access |
123+
| **1** | Personal project servers | Registered agents |
124+
| **2** | Production read-only tools | Domain-verified agents |
125+
| **3** | Write operations | Org-verified agents |
126+
| **4** | Admin tools | Enterprise agents |
127+
128+
---
129+
130+
## Next Steps
131+
132+
<div class="grid cards" markdown>
133+
134+
- [:material-shield-check: **Protect Your Tools**](../../mcp-guard/guides/server-side/)
135+
136+
Add `@guard` to your MCP server tools
137+
138+
- [:material-check-decagram: **Verify Servers**](../../mcp-guard/guides/client-side/)
139+
140+
Implement server verification in your MCP client
141+
142+
- [:material-file-document: **Evidence Logging**](../../mcp-guard/guides/evidence/)
143+
144+
Set up cryptographic audit trails
145+
146+
- [:material-api: **API Reference**](../../reference/sdk-python/mcp/)
147+
148+
Complete MCP Guard API documentation
149+
150+
</div>

‎docs/getting-started/index.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,16 @@ npm install -g capiscio # or: pip install capiscio
5353

5454
[:octicons-arrow-right-24: Add Security](secure/1-intro.md)
5555

56+
- :material-tools:{ .lg .middle } **Protect MCP Tools**
57+
58+
---
59+
60+
Add tool-level authorization to Model Context Protocol servers.
61+
62+
**10 minutes** · Intermediate
63+
64+
[:octicons-arrow-right-24: MCP Guard Quickstart](../mcp-guard/getting-started/quickstart.md)
65+
5666
- :material-pipe:{ .lg .middle } **CI/CD Integration**
5767

5868
---

‎docs/how-to/index.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,17 @@ Task-oriented guides for specific problems. Each guide is self-contained with co
4747

4848
---
4949

50+
## :material-tools: MCP Guard
51+
52+
| Guide | What You'll Do | Time |
53+
|-------|----------------|------|
54+
| [Protect MCP Tools](../mcp-guard/guides/server-side.md) | Add `@guard` decorator to MCP tools | 5 min |
55+
| [Verify MCP Servers](../mcp-guard/guides/client-side.md) | Verify server identity before connecting | 5 min |
56+
| [Evidence Logging](../mcp-guard/guides/evidence.md) | Log tool calls for compliance | 5 min |
57+
| [MCP SDK Integration](../mcp-guard/guides/mcp-integration.md) | Integrate with official MCP SDK | 10 min |
58+
59+
---
60+
5061
## :material-pipe: CI/CD
5162

5263
| Guide | What You'll Do | Time |

0 commit comments

Comments
 (0)