Authentication | Chipp Docs

The Chipp MCP Server supports two authentication methods: OAuth 2.0 with PKCE (for interactive MCP clients) and API Keys (for automation and scripts). This page explains both methods and how to troubleshoot common issues.

OAuth Authentication

How It Works

ℹ️

You don’t need to write any code. Your MCP client handles the OAuth flow automatically.

When you first use a Chipp MCP tool:

Your MCP client opens a browser window to the Chipp authorization page
You log in with your Chipp account (or are already logged in)
You approve the connection by clicking “Authorize”
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:

plaintext

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:

Token Type	Prefix	Lifetime	What It Does
Access Token	`chipp_at_`	1 hour	Authenticates each request
Refresh Token	`chipp_rt_`	30 days	Gets new access tokens when they expire

Your MCP client:

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

API Keys

For automation, CI/CD pipelines, and scripts, API keys provide non-interactive authentication without the OAuth browser flow.

Creating an API Key

Go to Settings > Developer > API Keys in your Chipp dashboard
Click Create Key and give it a descriptive name
Optionally select specific permission scopes (or leave as full access)
Optionally set an expiration (30 days, 90 days, 1 year, or never)
Copy the key immediately — it is shown only once

Key Format

API keys use the chipp_sk_ prefix:

plaintext

chipp_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v

Using API Keys

Pass the API key as a Bearer token:

json

{
  "mcpServers": {
    "chipp": {
      "url": "https://build.chipp.ai/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer chipp_sk_xxxxx"
      }
    }
  }
}

Or in direct HTTP requests:

bash

curl -X POST https://build.chipp.ai/mcp \
  -H "Authorization: Bearer chipp_sk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Key Security

Keys are hashed in the database — we cannot retrieve your key after creation
Keys can be scoped to specific permissions (e.g., read-only access)
Keys never expire by default — optionally set 30-day, 90-day, or 1-year expiration
Keys can be revoked instantly from the Developer settings page

⚠️

Treat API keys like passwords. Never commit them to source control or share them in plaintext. Use environment variables or secret managers.

Permission Scopes

Both OAuth tokens and API keys use the same permission scopes:

Scope	What It Allows
`apps:read`	View your apps
`apps:write`	Create, update, delete apps
`knowledge:read`	View knowledge sources
`knowledge:write`	Add, update, delete knowledge sources
`actions:read`	View custom actions
`actions:write`	Manage custom actions
`analytics:read`	View conversation analytics
`workspace:read`	View workspace information
`workspace:write`	Create and update workspaces
`billing:read`	View subscription and credits
`*`	All permissions

Revoking Access

Revoking OAuth Tokens

To disconnect an MCP client from your Chipp account, you can revoke your tokens programmatically:

bash

# Revoke your refresh token
curl -X POST https://build.chipp.ai/mcp/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "chipp_rt_your_refresh_token", "token_type_hint": "refresh_token"}'

For Claude Code, you can also clear your stored credentials to force re-authorization:

bash

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

Revoking API Keys

Go to Settings > Developer > API Keys in your Chipp dashboard and click Delete next to the key you want to revoke. The key is deactivated immediately.

After revoking or clearing credentials, 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:

Restart your MCP client (e.g., restart Claude Code)
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:

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

”Invalid token format”

What happened: The stored token is corrupted or incomplete.

Fix:

Clear your MCP client’s stored Chipp credentials
Re-authorize from scratch

For Claude Code, you can reset credentials:

bash

# 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:

Ensure you complete the browser authorization within 5 minutes
Check your internet connection
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
S256 challenge method required — plain method is not supported
No client secret required - safe for desktop applications
Short-lived access tokens - minimize exposure if compromised
Refresh token rotation - each refresh immediately revokes the previous access token and refresh token, and issues a new pair. Store the new tokens before discarding the response

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

Endpoint	Method	Purpose
`https://build.chipp.ai/mcp/oauth/authorize`	GET	Start authorization
`https://build.chipp.ai/mcp/oauth/token`	POST	Exchange code for tokens
`https://build.chipp.ai/mcp/oauth/register`	POST	Dynamic client registration
`https://build.chipp.ai/mcp/oauth/revoke`	POST	Revoke tokens
`https://build.chipp.ai/.well-known/oauth-authorization-server`	GET	OAuth discovery

Authorization Request

plaintext

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

Token Exchange

bash

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

{
  "grant_type": "authorization_code",
  "code": "AUTH_CODE",
  "redirect_uri": "http://localhost:PORT/callback",
  "client_id": "chipp_mcp_cli",
  "code_verifier": "PKCE_VERIFIER"
}

Token Refresh

bash

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

{
  "grant_type": "refresh_token",
  "refresh_token": "chipp_rt_xxx",
  "client_id": "chipp_mcp_cli"
}

Next Steps

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