docs: clarify instructions

Author: kamil-keycard

README.md

@@ -63,6 +63,10 @@ Refer to [docs](https://docs.keycard.ai/) on how to signup. Navigate to Zone Set
 
 ![Keycard ZoneId Information](docs/images/keycard_zone_information.png)
 
+### Configure Your prefered Identity Provider
+
+![Keycard Identity Provider Configuration](docs/images/keycard_identity_provider_config.png)
+
 ### Setup MCP resource
 
 ![Create MCP Resource](docs/images/create_mcp_resource.png)
@@ -114,14 +118,13 @@ pip install uvicorn
 uvicorn server:app
 ```
 
-Your MCP server is now running with KeyCard authentication! 🎉
-
-
 ### Authenticate in client
 
 ![Cursor Authentication Prompt](docs/images/cursor_authenticate.png)
 
-> **Need a KeyCard zone?** Sign up at [keycard.cloud](https://keycard.cloud) to get your zone ID and start building secure MCP applications.
+
+### 🎉 Your MCP server is now running with KeyCard authentication! 🎉
+
 
 ## Overview
 

docs/images/keycard_identity_provider_config.png

@@ -10,171 +10,71 @@ pip install keycardai-mcp
 
 ## Quick Start
 
-```python
-from keycardai.mcp import *
-
-# MCP Server with authentication
-server = MCPServer(
-    name="my-mcp-server",
-    version="1.0.0",
-    auth_config=MCPAuthConfig(
-        oauth_client_id="your_client_id",
-        oauth_client_secret="your_client_secret"
-    )
-)
+Add KeyCard authentication to your existing MCP server:
 
-# Register authenticated resources
-@server.resource("user-data")
-async def get_user_data(context: MCPContext) -> MCPResource:
-    # Automatic token validation and user context
-    user = context.authenticated_user
-    return MCPResource(
-        uri=f"user://{user.id}/data",
-        content=await fetch_user_data(user.id)
-    )
-
-# MCP Client with token management
-client = MCPClient(
-    server_url="https://api.example.com/mcp",
-    auth=MCPOAuthAuth(
-        client_id="client_id",
-        client_secret="client_secret"
-    )
-)
+### Install the Package
 
-# Access authenticated resources
-user_data = await client.get_resource("user-data")
+```bash
+pip install keycardai-mcp
 ```
 
-## 🏗️ Architecture & Features
-
-This SDK provides comprehensive MCP functionality with enterprise-grade security:
-
-### Core MCP Components
+### Get Your KeyCard Zone ID
 
-| Component | Module | Description |
-|-----------|---------|-------------|
-| **MCP Server** | `server.py` | **Authenticated MCP Server** - Host MCP resources with built-in OAuth 2.0 authentication |
-| **MCP Client** | `client.py` | **Secure MCP Client** - Connect to MCP servers with automatic token management |
-| **Resource Management** | `resources.py` | **Authenticated Resources** - Secure resource access with user context |
-| **Tool Integration** | `tools.py` | **Secure Tools** - Execute MCP tools with proper authorization |
+1. Sign up at [keycard.ai](https://keycard.ai)
+2. Navigate to Zone Settings to get your zone ID
+3. Configure your preferred identity provider
+4. Create an MCP resource in your zone
 
-### Authentication & Security
+### Add Authentication to Your MCP Server
 
-| Feature | Module | Description |
-|---------|---------|-------------|
-| **OAuth 2.0 Integration** | `auth.py` | **Token Management** - Seamless OAuth integration for MCP operations |
-| **Token Validation** | `validation.py` | **Security Middleware** - Automatic token validation and user context |
-| **Scope Management** | `scopes.py` | **Permission Control** - Fine-grained access control for MCP resources |
-| **Session Management** | `sessions.py` | **Secure Sessions** - Persistent authenticated sessions for MCP clients |
-
-### MCP Protocol Extensions
-
-| Standard | Module | Description |
-|----------|---------|-------------|
-| **Resource Templates** | `templates.py` | **Dynamic Resources** - Template-based resource generation with auth context |
-| **Prompt Security** | `prompts.py` | **Secure Prompts** - User-aware prompt templates and execution |
-| **Tool Authorization** | `tools.py` | **Permission Checks** - Role-based access control for MCP tools |
-| **Logging & Monitoring** | `monitoring.py` | **Security Audit** - Comprehensive logging of authenticated operations |
-
-## Features
+```python
+from mcp.server.fastmcp import FastMCP
+from keycardai.mcp.server.auth import AuthProvider
 
-- ✅ **MCP Protocol Compliance**: Full implementation of Model Context Protocol standards
-- ✅ **OAuth 2.0 Integration**: Seamless authentication with industry-standard OAuth flows
-- ✅ **Type Safe**: Full type hints with Pydantic models for all MCP operations
-- ✅ **Async Support**: Native async/await support for all MCP operations
-- ✅ **Enterprise Security**: Token validation, scope management, and audit logging
-- ✅ **Developer Friendly**: Simplified API that abstracts away authentication complexity
-- ✅ **Production Ready**: Battle-tested security patterns and comprehensive error handling
+# Your existing MCP server
+mcp = FastMCP("My Secure MCP Server")
 
-## Use Cases
+@mcp.tool()
+def my_protected_tool(data: str) -> str:
+    return f"Processed: {data}"
 
-### 🤖 AI Agent Platforms
-```python
-# Secure MCP server for AI agents
-server = MCPServer(auth_required=True)
-
-@server.tool("execute-query")
-async def execute_query(context: MCPContext, query: str) -> dict:
-    # Only authenticated users with 'query:execute' scope
-    if not context.has_scope("query:execute"):
-        raise MCPAuthError("Insufficient permissions")
-    
-    return await database.execute(query, user=context.user)
-```
-
-### 🔐 Enterprise LLM Integration
-```python
-# Corporate LLM with secure resource access
-client = MCPClient(
-    server_url="https://corp-llm.company.com/mcp",
-    auth=MCPOAuthAuth.from_client_credentials(
-        client_id="corp-client",
-        client_secret="secret",
-        scopes=["documents:read", "calendar:read"]
-    )
+# Add KeyCard authentication
+access = AuthProvider(
+    zone_id="your_zone_id_here",
+    mcp_server_name="My Secure MCP Server",
 )
 
-# Access corporate resources securely
-documents = await client.list_resources("documents")
+# Create authenticated app
+app = access.app(mcp)
 ```
 
-### 🌐 Multi-Tenant SaaS
-```python
-# Tenant-aware MCP resources
-@server.resource("tenant-data")
-async def get_tenant_data(context: MCPContext) -> MCPResource:
-    tenant_id = context.user.tenant_id
-    return await fetch_tenant_data(tenant_id, user=context.user)
-```
-
-## Security Best Practices
-
-### Token Management
-- Automatic token refresh and rotation
-- Secure token storage with encryption
-- Scope-based permission validation
-- Session timeout and cleanup
-
-### Authentication Flows
-- Authorization Code flow for web applications
-- Client Credentials flow for service-to-service
-- Device Code flow for CLI applications
-- PKCE for public clients
+### Run with Authentication
 
-### Monitoring & Compliance
-- Comprehensive audit logging
-- Rate limiting and abuse prevention
-- GDPR-compliant user data handling
-- SOC 2 security controls
-
-## Development
+```bash
+pip install uvicorn
+uvicorn server:app
+```
 
-This package is part of the [KeycardAI Python SDK workspace](../../README.md). 
+### 🎉 Your MCP server is now protected with KeyCard authentication! 🎉
 
-To develop:
+## Features
 
-```bash
-# From workspace root
-uv sync
-uv run --package keycardai-mcp pytest
-```
+- ✅ **OAuth 2.0 Authentication**: Secure your MCP server with industry-standard OAuth flows
+- ✅ **Easy Integration**: Add authentication with just a few lines of code
+- ✅ **Multi-Zone Support**: Support multiple KeyCard zones in one application
+- ✅ **Token Exchange**: Automatic delegated token exchange for accessing external APIs
+- ✅ **Production Ready**: Battle-tested security patterns and error handling
 
 ## Examples
 
-See the [examples directory](examples/) for comprehensive examples including:
-- Basic MCP server setup
-- OAuth integration patterns
-- Multi-tenant configurations
-- Enterprise deployment guides
+For complete examples and advanced usage patterns, see our [documentation](https://docs.keycard.ai).
 
 ## License
 
 MIT License - see [LICENSE](../../LICENSE) file for details.
 
 ## Support
 
-- 📖 [Documentation](https://docs.keycardai.com/mcp)
+- 📖 [Documentation](https://docs.keycard.ai)
 - 🐛 [Issue Tracker](https://github.com/keycardai/python-sdk/issues)
-- 💬 [Community Discussions](https://github.com/keycardai/python-sdk/discussions)
 - 📧 [Support Email](mailto:support@keycard.ai)