Python SDK
Keycard Python SDK
Installation
npx python-sdkAsk AI about Python SDK
Powered by Claude Β· Grounded in docs
I know everything about Python SDK. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Keycard Python SDK
Keycard handles OAuth, identity, and access so your MCP servers don't have to. Add authentication, authorization, and delegated API access to any MCP server with a few lines of Python β no token plumbing, no auth middleware, no security footguns.
- Drop-in auth for MCP servers (OAuth 2.0, PKCE, token exchange β handled for you)
- Delegated access β call Google, GitHub, Slack APIs on behalf of your users with automatic token exchange
- Works with both the MCP Python SDK and the FastMCP framework
Which Package?
| You want to... | Install | Guide |
|---|---|---|
Add auth to MCP servers (using the mcp SDK) | pip install keycardai-mcp | Quick Start |
| Add auth to FastMCP servers | pip install keycardai-fastmcp | Quick Start |
| Connect to MCP servers as a client | pip install keycardai-mcp | MCP Client docs |
| Build agent-to-agent (A2A) services | pip install keycardai-agents | Agents docs |
| Use the OAuth 2.0 client directly | pip install keycardai-oauth | OAuth docs |
Key Concepts
- Zone β A Keycard environment that groups your identity providers, MCP resources, and access policies. Get your zone ID from console.keycard.ai.
- Delegated Access β Calling external APIs (Google, GitHub, Slack, etc.) on behalf of your authenticated users via RFC 8693 token exchange.
@grantdecorator β Declares which external APIs a tool needs. Automatically exchanges the user's token for a scoped token before your function runs.- AccessContext β The result of a grant. Contains exchanged tokens or errors. Non-throwing by design β always check
.has_errors()before using tokens. - Application Credentials β How your server authenticates with Keycard for token exchange. Three types:
ClientSecret,WebIdentity,EKSWorkloadIdentity.
Known Limitations & Non-Goals
Current Limitations
- Alpha Status: All packages are in early development (
Development Status :: 3 - Alpha). APIs may change between minor versions. - FastMCP 3.x Required: The
keycardai-fastmcppackage requires FastMCP 3.0 or later. FastMCP 3.0 madectx.get_state()andctx.set_state()async; all tool functions using these calls must beasync def. - MCP Protocol Version: Tested against MCP protocol version as implemented by
mcp>=1.13.1. Newer MCP protocol versions may introduce incompatibilities.
Non-Goals
- Standalone Identity Provider: Keycard SDKs are designed to integrate with Keycard's hosted identity service, not to provide standalone identity management.
- Multi-Language Support: This SDK is Python-only. Other language SDKs are separate projects.
- Offline Operation: All authentication flows require network connectivity to Keycard services.
Compatibility Matrix
Python Version Support
| Python Version | Status |
|---|---|
| 3.9 | Not Supported |
| 3.10 | Supported (minimum) |
| 3.11 | Supported |
| 3.12 | Supported |
| 3.13 | Supported |
Key Dependency Constraints
| Package | Dependency | Version Constraint | Rationale |
|---|---|---|---|
keycardai-fastmcp | fastmcp | >=3.0.0 | FastMCP 3.0+ required. ctx.get_state()/ctx.set_state() are now async. |
| All packages | pydantic | >=2.11.7 | No upper bound - Pydantic 2.x maintains backward compatibility. |
| All packages | httpx | >=0.27.2 | No upper bound - httpx follows semver. |
keycardai-mcp | mcp | >=1.13.1 | No upper bound - API is protocol-defined. |
Why No Upper Bounds on Most Dependencies?
Following Python packaging best practices:
- Upper bounds cause resolver conflicts in end-user projects when multiple packages specify conflicting ranges.
- Well-maintained libraries (pydantic, httpx) follow semantic versioning and maintain backward compatibility.
- Testing against latest via CI catches issues before users encounter them.
Versioning & Breaking Changes
Versioning Strategy
All packages follow Semantic Versioning:
- MAJOR.MINOR.PATCH (e.g.,
0.15.0) - During
0.x.ydevelopment:- MINOR bumps (
0.x.0) may contain breaking changes - PATCH bumps (
0.x.y) are backward-compatible bug fixes
- MINOR bumps (
Alpha Status (0.x.y)
All packages are currently in alpha status. This means:
- API Stability: Public APIs may change between minor versions
- Documentation: APIs are documented but may evolve
- Production Use: Suitable for early adopters comfortable with potential migration work
When Will Packages Reach 1.0?
Packages will graduate to 1.0.0 when:
- Public API is stable and well-documented
- Comprehensive test coverage exists
- Production usage validates the design
- No planned breaking changes for foreseeable future
Breaking Change Policy
- Breaking changes are documented in CHANGELOG.md with migration guides
- Deprecation warnings will be added before removal where feasible
- Commit messages use
!suffix (e.g.,feat!:) for breaking changes - Release notes highlight breaking changes prominently
mcpvsfastmcp: ThemcpSDK includes a built-inFastMCPclass (from mcp.server.fastmcp import FastMCP), whilefastmcpis a separate standalone framework (from fastmcp import FastMCP). They're different libraries.keycardai-mcpwraps the former;keycardai-fastmcpwraps the latter.
Prerequisites
- Python 3.10+ and a virtual environment
- Sign up at keycard.ai and get your zone ID from Zone Settings
- Configure an identity provider (Google, Microsoft, etc.) and create an MCP resource in your zone
Quick Start: FastMCP
uv add keycardai-fastmcp fastmcp
from fastmcp import FastMCP
from keycardai.fastmcp import AuthProvider
# Configure Keycard authentication
auth_provider = AuthProvider(
zone_id="your-zone-id", # From console.keycard.ai
mcp_server_name="My Server",
mcp_base_url="http://localhost:8000/"
)
# Create authenticated MCP server
auth = auth_provider.get_remote_auth_provider()
mcp = FastMCP("My Server", auth=auth)
@mcp.tool()
def hello_world(name: str) -> str:
"""Say hello to someone."""
return f"Hello, {name}!"
if __name__ == "__main__":
mcp.run(transport="streamable-http")
See the FastMCP examples for runnable projects.
Quick Start: Standard MCP
pip install keycardai-mcp uvicorn
from mcp.server.fastmcp import FastMCP
from keycardai.mcp.server.auth import AuthProvider
import uvicorn
# Your MCP server
mcp = FastMCP("My Server")
@mcp.tool()
def hello_world(name: str) -> str:
"""Say hello to someone."""
return f"Hello, {name}!"
# Add Keycard authentication
auth_provider = AuthProvider(
zone_id="your-zone-id", # From console.keycard.ai
mcp_server_name="My Server",
mcp_server_url="http://localhost:8000/"
)
# Wrap with auth and run
app = auth_provider.app(mcp)
uvicorn.run(app, host="0.0.0.0", port=8000)
See the MCP examples for runnable projects.
Delegated Access
Delegated access lets your MCP tools call external APIs (Google Calendar, GitHub, Slack, etc.) on behalf of authenticated users via automatic token exchange.
Setup: Get client credentials from console.keycard.ai, then set KEYCARD_CLIENT_ID and KEYCARD_CLIENT_SECRET as environment variables.
FastMCP
import os
import httpx
from fastmcp import FastMCP, Context
from keycardai.fastmcp import AuthProvider, AccessContext, ClientSecret
auth_provider = AuthProvider(
zone_id="your-zone-id",
mcp_server_name="My Server",
mcp_base_url="http://localhost:8000/",
application_credential=ClientSecret((
os.getenv("KEYCARD_CLIENT_ID"),
os.getenv("KEYCARD_CLIENT_SECRET")
))
)
auth = auth_provider.get_remote_auth_provider()
mcp = FastMCP("My Server", auth=auth)
@mcp.tool()
@auth_provider.grant("https://www.googleapis.com/calendar/v3")
async def get_calendar_events(ctx: Context) -> dict:
"""Get the user's calendar events with delegated access."""
# Retrieve access context from FastMCP context
access_context: AccessContext = await ctx.get_state("keycardai")
if access_context.has_errors():
return {"error": f"Token exchange failed: {access_context.get_errors()}"}
token = access_context.access("https://www.googleapis.com/calendar/v3").access_token
async with httpx.AsyncClient() as client:
response = await client.get(
"https://www.googleapis.com/calendar/v3/calendars/primary/events",
headers={"Authorization": f"Bearer {token}"}
)
response.raise_for_status()
return response.json()
Standard MCP
import os
import httpx
from mcp.server.fastmcp import FastMCP, Context
from keycardai.mcp.server.auth import AuthProvider, AccessContext, ClientSecret
auth_provider = AuthProvider(
zone_id="your-zone-id",
mcp_server_name="My Server",
mcp_server_url="http://localhost:8000/",
application_credential=ClientSecret((
os.getenv("KEYCARD_CLIENT_ID"),
os.getenv("KEYCARD_CLIENT_SECRET")
))
)
mcp = FastMCP("My Server")
@mcp.tool()
@auth_provider.grant("https://www.googleapis.com/calendar/v3")
async def get_calendar_events(access_ctx: AccessContext, ctx: Context) -> dict:
"""Get the user's calendar events with delegated access."""
# @grant requires both AccessContext (for tokens) and Context (for request state)
if access_ctx.has_errors():
return {"error": f"Token exchange failed: {access_ctx.get_errors()}"}
token = access_ctx.access("https://www.googleapis.com/calendar/v3").access_token
async with httpx.AsyncClient() as client:
response = await client.get(
"https://www.googleapis.com/calendar/v3/calendars/primary/events",
headers={"Authorization": f"Bearer {token}"}
)
response.raise_for_status()
return response.json()
app = auth_provider.app(mcp)
Key difference: In
keycardai-mcp, the@grantdecorator requires bothaccess_ctx: AccessContextandctx: Contextas function parameters. Inkeycardai-fastmcp,AccessContextis retrieved from the FastMCPContextviaawait ctx.get_state("keycardai").
For complete delegated access examples with error handling patterns, see:
Connecting Your AI Client
Configure the remote MCP in your AI client (e.g., Cursor):
{
"mcpServers": {
"my-server": {
"url": "http://localhost:8000/mcp"
}
}
}
Using FastAPI
Mounting a FastMCP server into a larger FastAPI service introduces a few gotchas, particularly related to the various OAuth metadata endpoints.
Standards Compliant Approach
[!NOTE] Most MCP clients expect standards-compliance. Follow this approach if you're using those clients or the official MCP SDKs.
The OAuth spec declares that your metadata must be exposed at the root of your service.
/.well-known/oauth-protected-resource
This causes a problem when you're mounting multiple APIs or MCP servers to a common FastAPI service. Each API or MCP Server will potentially have their own OAuth metadata.
The OAuth spec defines that the metadata for each individual service should be
exposed as an extension to the base well-known URI. For example:
/.well-known/oauth-protected-resource/api
/.well-known/oauth-protected-resource/mcp-server/mcp
To ensure FastMCP and FastAPI produce this, you need to ensure your routing is defined in a specific way:
from fastmcp import FastMCP
from fastapi import FastAPI
mcp = FastMCP("MCP Server")
mcp_app = mcp.http_app() # DO NOT specify a path here
app = FastAPI(title="API", lifespan=mcp_app.lifespan)
# You MUST mount the MCP's `http_app` to the full path for FastMCP to expose the
# OAuth metadata correctly.
app.mount("/mcp-server/mcp", mcp_app)
Custom, Non Standards Compliant, Approach
[!WARNING] This is not advised. Only follow this if you know for sure you need flexibility outside of what the spec requires.
If you've built custom clients or need to mount the metadata at a different, non standards compliant, location, you can do that manually.
Mounting at a Custom Root
from fastmcp import FastMCP
from fastapi import FastAPI
from keycardai.mcp.server.routers.metadata import well_known_metadata_mount
auth_provider = AuthProvider(
zone_id="your-zone-id",
mcp_server_name="My Server",
mcp_base_url="http://127.0.0.1:8000/"
)
auth = auth_provider.get_remote_auth_provider()
mcp = FastMCP("MCP Server", auth=auth)
mcp_app = mcp.http_app()
app = FastAPI(title="API", lifespan=mcp_app.lifespan)
app.mount(
"/custom-well-known",
well_known_metadata_mount(issuer=auth.zone_url),
)
which will produce the following endpoints
/custom-well-known/oauth-protected-resource
/custom-well-known/oauth-authorization-server
Mounting at a Specific URI
If you need even more control, you can mount the individual routes at a specific URI.
from fastmcp import FastMCP
from fastapi import FastAPI
from keycardai.mcp.server.routers.metadata import (
well_known_authorization_server_route,
well_known_protected_resource_route,
)
auth_provider = AuthProvider(
zone_id="your-zone-id",
mcp_server_name="My Server",
mcp_base_url="http://127.0.0.1:8000/"
)
auth = auth_provider.get_remote_auth_provider()
mcp = FastMCP("MCP Server", auth=auth)
mcp_app = mcp.http_app()
app = FastAPI(title="API", lifespan=mcp_app.lifespan)
app.router.routes.append(
well_known_protected_resource_route(
path="/my/custom/path/to/well-known/oauth-protected-resource",
issuer=auth.zone_url,
)
)
app.router.routes.append(
well_known_authorization_server_route(
path="/my/custom/path/to/well-known/oauth-authorization-server",
issuer=auth.zone_url,
)
)
which will produce the following endpoints
/my/custom/path/to/well-known/oauth-protected-resource
/my/custom/path/to/well-known/oauth-authorization-server
FAQ
How to test the MCP server with modelcontextprotocol/inspector?
When testing your MCP server with the modelcontextprotocol/inspector, you may need to configure CORS to allow the inspector's web interface to access your protected endpoints from localhost.
Note: This applies specifically to keycardai-mcp. When using keycardai-fastmcp, no middleware is currently required as FastMCP permits access to metadata endpoints by default.
from starlette.middleware import Middleware
from starlette.middleware.cors import CORSMiddleware
middleware = [
Middleware(
CORSMiddleware,
allow_origins=["*"], # For local dev only
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
]
app = auth_provider.app(mcp, middleware=middleware)
Important: The allow_origins=["*"] setting is for local development only. In production, restrict to specific domains.
Documentation
- Full documentation β API reference, tutorials, integration guides
- Package docs:
- keycardai-mcp β MCP server authentication
- keycardai-fastmcp β FastMCP integration
- keycardai-mcp client β MCP client (CLI, web apps, AI agent integrations)
- keycardai-agents β Agent-to-agent delegation (A2A)
- keycardai-oauth β OAuth 2.0 client
- Examples: MCP Β· FastMCP Β· OAuth Β· Agents
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
- GitHub Issues: https://github.com/keycardai/python-sdk/issues
- Documentation: https://docs.keycard.ai
- Email: support@keycard.ai
