Setting Up Stytch OAuth for BioMCP

This document outlines the steps required to set up Stytch OAuth authentication for the BioMCP application.

Prerequisites

• A Stytch account (sign up at Stytch)
• Access to the BioMCP codebase

Setting Up Your Stytch Account

1. Create a Stytch Account

2. Sign up at Stytch

3. Select "Consumer Authentication" when prompted during the setup process

4. Configure the Stytch Project

5. In the Stytch dashboard, navigate to "Frontend SDKs" and enable the frontend SDK

6. Navigate to "Connected Apps" and enable "Dynamic Client Registration"

7. This allows MCP clients to register themselves dynamically with Stytch

8. Retrieve Your Credentials

9. Go to "Project Settings" in the Stytch dashboard
10. Note down the following credentials:
    • Project ID
    • Secret (API Key)
    • Public Token

Configuring BioMCP with Stytch

1. Update the Wrangler Configuration

2. Open wrangler.toml in the BioMCP project

3. Update the following variables with your Stytch credentials:

   STYTCH_PROJECT_ID = "your-project-id"
   STYTCH_SECRET = "your-secret-key"
   STYTCH_PUBLIC_TOKEN = "your-public-token"
   

4. For development, use the test environment:

   STYTCH_API_URL = "https://test.stytch.com/v1"
   

5. For production, use:

   STYTCH_API_URL = "https://api.stytch.com/v1"
   

6. Configure the OAuth KV Namespace

7. Create a KV namespace in Cloudflare for storing OAuth tokens and state

8. Update the KV namespace ID in wrangler.toml:

   [[kv_namespaces]]
   binding = "OAUTH_KV"
   id = "your-kv-namespace-id"
   

9. Configure JWT Secret

10. Set a strong JWT secret for token signing:

    JWT_SECRET = "your-secure-jwt-secret"
    

OAuth Flow Overview

The BioMCP application uses the following OAuth flow:

1. Discovery: MCP clients fetch OAuth metadata to locate Stytch authorization endpoints
2. Registration: MCP clients dynamically register with Stytch
3. Authorization: Users are redirected to Stytch for authentication and consent
4. Token Exchange: After consent, authorization codes are exchanged for access tokens
5. MCP Connection: MCP clients connect to the BioMCP server using OAuth access tokens

Endpoints

The worker implements the following OAuth endpoints:

• /.well-known/oauth-authorization-server: OAuth server metadata
• /authorize: OAuth authorization endpoint
• /callback: OAuth callback endpoint
• /token: Token exchange endpoint

Testing

To test the OAuth implementation:

1. Deploy the worker to Cloudflare:

wrangler deploy

1. Use the MCP Inspector or another OAuth client to test the flow:
2. Set the OAuth discovery URL to: https://your-worker.workers.dev/.well-known/oauth-authorization-server
3. The inspector will guide you through the OAuth flow

Troubleshooting

• JWT Validation Issues: Ensure the JWKS endpoint is correctly configured and accessible
• Callback Errors: Check that the redirect URIs are properly registered and match exactly
• Token Exchange Failures: Verify that the authorization code is valid and not expired

Security Considerations

• Always use HTTPS for all OAuth endpoints
• Implement proper CORS headers for cross-origin requests
• Regularly rotate the JWT secret
• Use the production Stytch API URL for production environments