keycardai-mcp-fastmcp 0.2.0

FastMCP integration for KeyCard OAuth client with automated token exchange and authentication

KeyCard AI FastMCP Integration

A Python package that provides seamless integration between KeyCard and FastMCP servers, enabling secure token exchange and authentication for MCP tools.

Installation

pip install keycardai-mcp-fastmcp

Quick Start

from fastmcp import FastMCP, Context
from keycardai.mcp.integrations.fastmcp import KeycardAuthProvider, OAuthClientMiddleware, get_access_token_for_resource

# Create FastMCP server with KeyCard authentication
mcp = FastMCP("My Secure Service")

# Add KeyCard authentication
auth = KeycardAuthProvider(
    zone_url="https://abc1234.keycard.cloud",
    mcp_server_name="My MCP Service"
)
mcp.set_auth_provider(auth)

# Add OAuth client middleware for token exchange
oauth_middleware = OAuthClientMiddleware(
    zone_url="https://abc1234.keycard.cloud",
    client_name="My MCP Service"
)
mcp.add_middleware(oauth_middleware)

# Use decorator for automatic token exchange
@mcp.tool()
@get_access_token_for_resource("https://www.googleapis.com/calendar/v3")
async def get_calendar_events(ctx: Context, maxResults: int = 10) -> dict:
    # ctx.access_token is automatically available with Google Calendar access
    access_token = ctx.access_token
    # Make API calls with the exchanged token...
    return {"events": [...], "totalEvents": 5}

🏗️ Architecture & Features

This integration package provides FastMCP-specific components for KeyCard OAuth:

Core Components

Component	Module	Description
KeycardAuthProvider	provider.py	FastMCP Authentication - Integrates KeyCard zone tokens with FastMCP auth system
OAuthClientMiddleware	middleware.py	Client Lifecycle - Manages OAuth client initialization and context injection
Token Exchange Decorators	decorators.py	Automated Exchange - Decorators for seamless resource-specific token exchange

Authentication Flow

1. Token Verification: KeycardAuthProvider validates incoming JWT tokens using KeyCard zone JWKS
2. Client Management: OAuthClientMiddleware provides OAuth client to tools via FastMCP context
3. Token Exchange: @get_access_token_for_resource() decorator automates RFC 8693 token exchange
4. API Access: Tools receive resource-specific access tokens transparently

Development

This package is part of the KeycardAI Python SDK.

To develop:

# From workspace root
uv sync
uv run --package keycardai-mcp-fastmcp pytest

License

MIT License - see LICENSE file for details.

Support

• 🐛 Issue Tracker
• 💬 Community Discussions
• 📧 Support Email