Tutorial: "Secure your first MCP tool in 5 minutes"

[dgenio]

Milestone: v0.3.0 | Tier: Strategic | Effort: Medium

Problem

No tutorial content exists. README.md has a ~10-line quickstart but doesn't walk through a real scenario. Users evaluating the library must reverse-engineer the examples and docstrings to understand:

• How capabilities, principals, and policies relate
• When to use each response mode
• How PII redaction works end-to-end
• How to connect to real tool backends (MCP)

The existing examples (basic_cli.py, billing_demo.py, http_driver_demo.py) are functional but not pedagogical.

Proposed Change

1. Tutorial document (docs/tutorial.md)

"Secure your first MCP tool in 5 minutes" — step-by-step guide:

1. Install: pip install agent-kernel
2. Define a capability (billing lookup)
3. Create a principal (agent identity)
4. Configure policy (what this agent is allowed to do)
5. Grant access and get a token
6. Invoke the capability
7. Observe firewall redaction (PII fields masked)
8. Try a denied request (wrong role) and see the error
9. Connect to an MCP server (if MCP driver is available)

Each step has copy-pasteable code with expected output shown.

2. Self-contained tutorial script (examples/tutorial_mcp.py)

• Uses InMemoryDriver (no external dependencies)
• Demonstrates the full lifecycle: register → grant → invoke → expand → explain
• Shows policy enforcement (grant denied, reason explained)
• Shows firewall modes (summary vs. table vs. handle_only)
• Shows PII redaction before/after
• Prints clear annotated output explaining each step
• Runnable via python examples/tutorial_mcp.py with zero setup

3. Interactive Jupyter notebook (optional)

• examples/tutorial.ipynb — same content as the script but interactive
• Each cell has markdown explaining the concept, then code
• Useful for workshops, demos, and evaluation

4. README quickstart refresh

Update README.md quickstart to reference the tutorial and provide the minimal "wow" moment in 5 lines.

Acceptance Criteria

• docs/tutorial.md walks a new user from install to working invocation in <5 minutes
• examples/tutorial_mcp.py runs successfully with zero external dependencies
• Tutorial demonstrates: registration, policy enforcement (allow + deny), firewall redaction, expand/explain
• All code snippets in the tutorial are tested (either via doctest or by running the example in CI)
• README quickstart updated with clear pointer to tutorial
• Tutorial runs in CI (make ci or equivalent)

Affected Files

• docs/tutorial.md (new)
• examples/tutorial_mcp.py (new)
• examples/tutorial.ipynb (new, optional)
• README.md (quickstart refresh)

Dependencies

• Benefits from MCP Driver (OpenTelemetry integration: spans, metrics, and trace export #38) for MCP-specific tutorial section
• Can be started immediately with InMemoryDriver

[dgenio]

Dependency note: This issue is blocked by #41 / #53 (MCP Driver). The tutorial requires a working MCP Driver to demonstrate the "Secure your first MCP tool in 5 minutes" workflow.