|
| 1 | +--- |
| 2 | +title: "Key Concepts" |
| 3 | +description: "Core concepts and terminology used across the Keycard Python SDK" |
| 4 | +--- |
| 5 | + |
| 6 | +# Key Concepts |
| 7 | + |
| 8 | +This page defines the core terms used throughout the Keycard SDK. Each term links to the relevant documentation for deeper details. |
| 9 | + |
| 10 | +## Zone |
| 11 | + |
| 12 | +A **zone** is a Keycard environment that groups your identity providers, MCP resources, and access policies. Every Keycard integration starts with a zone. |
| 13 | + |
| 14 | +- **zone_id** — The unique identifier for your zone, used in SDK configuration |
| 15 | +- **zone_url** — The full URL of your zone's OAuth endpoints (alternative to zone_id) |
| 16 | + |
| 17 | +Get your zone ID from [console.keycard.ai](https://console.keycard.ai). You can use either `zone_id` or `zone_url` to configure the SDK — zone_id is simpler, zone_url gives more control. |
| 18 | + |
| 19 | +## Delegated Access |
| 20 | + |
| 21 | +**Delegated access** lets your MCP tools call external APIs (Google Calendar, GitHub, Slack, etc.) on behalf of your authenticated users. Under the hood, it uses [RFC 8693 token exchange](https://datatracker.ietf.org/doc/html/rfc8693) to swap the user's MCP token for a scoped token targeting the external API. |
| 22 | + |
| 23 | +See the [Delegated Access guide](examples/delegated-access) for how it works and how to set it up. |
| 24 | + |
| 25 | +## @grant Decorator |
| 26 | + |
| 27 | +The **`@grant` decorator** declares which external APIs a tool needs access to. It takes one or more audience URLs and automatically performs token exchange before your function runs. |
| 28 | + |
| 29 | +```python |
| 30 | +@auth_provider.grant("https://www.googleapis.com/calendar/v3") |
| 31 | +async def get_events(ctx: Context) -> dict: |
| 32 | + access_context = ctx.get_state("keycardai") |
| 33 | + token = access_context.access("https://www.googleapis.com/calendar/v3").access_token |
| 34 | + # Use token to call Google Calendar API |
| 35 | +``` |
| 36 | + |
| 37 | +## AccessContext |
| 38 | + |
| 39 | +**AccessContext** is the result of a grant. It contains the exchanged tokens (or errors) for each requested audience. It is **non-throwing by design** — token exchange failures are captured as errors on the context, not raised as exceptions. |
| 40 | + |
| 41 | +Always check before using tokens: |
| 42 | + |
| 43 | +```python |
| 44 | +if access_context.has_errors(): |
| 45 | + return {"error": access_context.get_errors()} |
| 46 | + |
| 47 | +token = access_context.access("https://api.example.com").access_token |
| 48 | +``` |
| 49 | + |
| 50 | +How you get the AccessContext depends on the package: |
| 51 | + |
| 52 | +| Package | How to get AccessContext | |
| 53 | +|---|---| |
| 54 | +| `keycardai-mcp-fastmcp` | `ctx.get_state("keycardai")` | |
| 55 | +| `keycardai-mcp` | Function parameter: `access_ctx: AccessContext` | |
| 56 | + |
| 57 | +## Application Credentials |
| 58 | + |
| 59 | +**Application credentials** are how your MCP server authenticates with Keycard for token exchange. They're required for [delegated access](#delegated-access). |
| 60 | + |
| 61 | +Three types are supported: |
| 62 | + |
| 63 | +| Type | Use Case | |
| 64 | +|---|---| |
| 65 | +| `ClientSecret` | Most common — client ID + secret pair | |
| 66 | +| `WebIdentity` | Private key JWT assertion ([RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523)) | |
| 67 | +| `EKSWorkloadIdentity` | AWS EKS workload identity for Kubernetes deployments | |
| 68 | + |
| 69 | +Set credentials via environment variables (`KEYCARD_CLIENT_ID`, `KEYCARD_CLIENT_SECRET`) or pass them explicitly in code. |
| 70 | + |
| 71 | +## AuthProvider |
| 72 | + |
| 73 | +**AuthProvider** is the main entry point for adding Keycard authentication to your MCP server. Each package has its own AuthProvider: |
| 74 | + |
| 75 | +- **FastMCP:** `from keycardai.mcp.integrations.fastmcp import AuthProvider` |
| 76 | +- **Standard MCP:** `from keycardai.mcp.server.auth import AuthProvider` |
| 77 | + |
| 78 | +The AuthProvider handles OAuth metadata serving, token validation, and (with application credentials) token exchange. |
| 79 | + |
| 80 | +## MCP Client |
| 81 | + |
| 82 | +The **MCP Client** connects *to* authenticated MCP servers. It handles OAuth flows, multi-server connections, and provides integrations for AI agent frameworks (LangChain, OpenAI Agents, CrewAI). |
| 83 | + |
| 84 | +See the [MCP Client documentation](https://github.com/keycardai/python-sdk/blob/main/packages/mcp/src/keycardai/mcp/client/README.md) for complete usage guide. |
0 commit comments