MCP OAuth Compliance

systemprompt fully complies with the Model Context Protocol OAuth draft specification, ensuring seamless authentication with any MCP server that follows the standard. If it works in the MCP inspector, it works with systemprompt.

OAuth Draft Specification

Full MCP Compliance

systemprompt implements the complete MCP OAuth draft spec:

• Authorization Code Flow with PKCE
• Automatic discovery via well-known endpoints
• Dynamic client registration support
• Token refresh handling
• Secure state management

How It Works

When connecting to an MCP server with OAuth:

1. Discovery Phase

   • Checks /.well-known/oauth-authorization-server
   • Falls back to /.well-known/openid-configuration
   • Extracts authorization and token endpoints

2. Authorization Flow

   • Generates PKCE code verifier/challenge
   • Opens system browser for authorization
   • Handles redirect via deep links
   • Exchanges code for tokens securely

3. Token Management

   • Stores tokens in device keychain
   • Automatic refresh before expiry
   • Graceful re-authentication when needed

Inspector Compatibility

Our Guarantee

If an MCP server works with the official MCP inspector, it will work with systemprompt.

This includes:

• Standard OAuth flows
• Custom authentication schemes
• Header-based authentication
• Token-based access
• Any inspector-compatible method

Testing Your Server

Before connecting to systemprompt:

# Test with MCP inspector
npx @modelcontextprotocol/inspector your-server-url
 
# If authentication works there, it works with us

Supported Authentication Methods

1. MCP OAuth (Primary)

The standard MCP OAuth implementation:

Server Config:
- OAuth discovery endpoint
- PKCE support required
- Standard scopes
- Refresh token support

2. Pre-configured OAuth

For popular services, we handle OAuth automatically:

• GitHub - Full OAuth with repo/gist/user scopes
• Sentry - Organization-based OAuth
• Shopify - Store authentication
• Make.com - Scenario access

3. Custom Schemes

Some MCP servers use alternative authentication:

• Bearer tokens in Authorization header
• API keys in custom headers
• Query parameters for tokens
• No authentication for local servers

Important: If it works in the MCP inspector, we support it.

Implementation Details

PKCE Security

All OAuth flows use PKCE (Proof Key for Code Exchange):

Code Verifier: Random 128-character string
Code Challenge: SHA256(verifier)
Challenge Method: S256

This prevents authorization code interception attacks.

Token Storage

Secure credential management:

iOS

• Keychain Services API
• Hardware encryption
• Biometric protection available

Android

• Android Keystore
• Hardware-backed keys
• Fingerprint/PIN protection

Automatic Refresh

Token refresh happens automatically:

1. Monitor expiry time from token response
2. Refresh proactively before expiration
3. Retry with backoff on failure
4. Re-authenticate if refresh fails

Setting Up OAuth

For MCP Servers

Your server just needs to:

1. Implement MCP OAuth spec
2. Provide discovery endpoint (recommended)
3. Support PKCE for security
4. Return standard tokens

In systemprompt

Users simply:

1. Add your server URL
2. Tap "Connect"
3. Authorize in browser
4. Start using tools

The app handles all complexity automatically.

Common Scenarios

GitHub Integration

Automatic OAuth with:
- Repo access
- Issue management
- PR operations
- Gist support

Sentry Connection

Organization-scoped OAuth:
- Error reading
- Issue assignment
- Project access
- Team management

Custom MCP Server

Your server with:
- Standard OAuth endpoints
- Custom scopes
- Refresh tokens
- PKCE support

Troubleshooting

OAuth Errors

"Authorization failed"

• Check server implements MCP spec
• Verify discovery endpoint works
• Ensure PKCE is supported
• Test with MCP inspector first

"Token refresh failed"

• Verify refresh endpoint
• Check token expiry handling
• Ensure refresh token provided
• Re-authenticate if needed

Debugging

Enable auth debugging:

1. Settings → Advanced
2. Enable "Auth Debug Mode"
3. View detailed OAuth logs
4. Check PKCE parameters
5. Verify token exchange

Server Implementation

Minimum Requirements

For MCP OAuth compliance:

// Discovery endpoint
GET /.well-known/oauth-authorization-server
{
  "authorization_endpoint": "https://example.com/oauth/authorize",
  "token_endpoint": "https://example.com/oauth/token",
  "code_challenge_methods_supported": ["S256"]
}
 
// Token response
{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "..."
}

Best Practices

1. Always use HTTPS
2. Implement token refresh
3. Support discovery endpoints
4. Return expiry information
5. Use standard error codes

Security Considerations

Why MCP OAuth?

• No password sharing - Users never give passwords to systemprompt
• Revocable access - Users can revoke from service
• Scoped permissions - Only requested access granted
• Industry standard - Based on OAuth 2.0 + PKCE

Additional Security

systemprompt adds extra security:

• System browser only - No in-app browsers
• Certificate pinning - For known services
• Secure storage - Hardware-backed encryption
• No token logging - Sensitive data never logged

Summary

• Full MCP OAuth draft spec compliance
• Inspector compatibility guaranteed
• Automatic handling of standard flows
• Support for custom authentication
• Secure token management
• Zero configuration for users

If your MCP server follows the spec or works with the inspector, systemprompt will authenticate seamlessly. No special configuration needed - we handle the complexity so users don't have to.