OAuth Authentication

When you connect an MCP client (like Claude Code or Cursor) to the Chipp MCP Server, authentication is handled automatically using OAuth 2.0 with PKCE. This page explains what happens during authentication and how to troubleshoot common issues.

How Authentication Works

When you first use a Chipp MCP tool:

1. Your MCP client opens a browser window to the Chipp authorization page
2. You log in with your Chipp account (or are already logged in)
3. You approve the connection by clicking "Authorize"
4. The browser closes and your MCP client is now connected

That's it! Your client stores the tokens securely and refreshes them automatically.

What You'll See

Authorization Screen

When prompted to authorize, you'll see:

• Chipp MCP Server as the application requesting access
• Your Chipp account email to confirm you're logged in
• Requested permissions (typically full access to your apps)
• Authorize and Deny buttons

After Authorization

Your MCP client will confirm the connection. In Claude Code, you might see:

Connected to Chipp MCP Server
Available tools: list_apps, create_app, get_app_analytics...

Token Management

Chipp uses prefixed tokens that your MCP client manages automatically:

Your MCP client:

• Stores tokens securely in its configuration
• Automatically refreshes expired access tokens
• Prompts you to re-authorize if the refresh token expires

Permission Scopes

When authorizing, your MCP client requests permissions. Most clients request full access (scope=*), which grants:

Revoking Access

To disconnect an MCP client from your Chipp account:

1. Go to Chipp Settings
2. Navigate to Connected Apps or API Access
3. Find the MCP connection and click Revoke

After revoking, your MCP client will prompt you to re-authorize the next time you use a Chipp tool.

Troubleshooting

"Authentication required"

What happened: Your token expired and couldn't be refreshed.

Fix: Your MCP client should automatically prompt you to re-authorize. If not:

1. Restart your MCP client (e.g., restart Claude Code)
2. Try using a Chipp tool again to trigger the auth flow

"Scope not authorized"

What happened: The tool requires a permission that wasn't granted.

Fix: Re-authorize with broader permissions. Most MCP clients request all scopes automatically, so this is rare.

Browser Doesn't Open

What happened: The auth flow couldn't open your default browser.

Fix:

1. Check if your MCP client logged a URL you can copy/paste
2. Ensure a default browser is configured on your system
3. Try restarting your MCP client

"Invalid token format"

What happened: The stored token is corrupted or incomplete.

Fix:

1. Clear your MCP client's stored Chipp credentials
2. Re-authorize from scratch

For Claude Code, you can reset credentials:

# Remove stored Chipp OAuth tokens
rm -rf ~/.claude/mcp-auth/chipp*

Connection Times Out

What happened: The authorization flow didn't complete in time.

Fix:

1. Ensure you complete the browser authorization within 5 minutes
2. Check your internet connection
3. Try again - the flow is quick once you know what to expect

Security Details

For those interested in the technical implementation:

OAuth 2.0 with PKCE

The Chipp MCP Server uses OAuth 2.0 Authorization Code Flow with PKCE:

• PKCE (Proof Key for Code Exchange) prevents authorization code interception
• No client secret required - safe for desktop applications
• Short-lived access tokens - minimize exposure if compromised
• Refresh token rotation - each refresh issues new tokens

Why OAuth Instead of API Keys?

Benefits:

• Revocable - disconnect access anytime from your Chipp settings
• Expiring - tokens automatically expire, limiting damage from leaks
• Auditable - see when and where your account was accessed
• Scoped - permissions can be restricted to specific operations

Token Storage

Your MCP client stores tokens securely:

• Claude Code - encrypted in ~/.claude/ directory
• Cursor - stored in application settings
• Custom clients - should use OS keychain or encrypted storage

OAuth Flow Reference

For developers building custom MCP clients or debugging issues:

Endpoints

Authorization Request

GET https://app.chipp.ai/api/mcp/oauth/authorize?
  client_id=chipp-mcp-client
  &redirect_uri=http://localhost:PORT/callback
  &response_type=code
  &scope=*
  &state=RANDOM_STATE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

Token Exchange

POST https://app.chipp.ai/api/mcp/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "AUTH_CODE",
  "redirect_uri": "http://localhost:PORT/callback",
  "client_id": "chipp-mcp-client",
  "code_verifier": "PKCE_VERIFIER"
}

Token Refresh

POST https://app.chipp.ai/api/mcp/oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "chipp_rt_xxx",
  "client_id": "chipp-mcp-client"
}

Next Steps

• Rate Limits - Understanding request limits
• Tools Reference - All available tools
• Common Workflows - Practical examples