# OAuth Authentication

How authentication works when connecting MCP clients to your Chipp account


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

<Callout type="info">
  You don't need to write any code. Your MCP client handles the OAuth flow automatically.
</Callout>

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:

| 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

## Permission Scopes

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

| 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 |
| `billing:read` | View subscription and credits |

---

## Revoking Access

To disconnect an MCP client from your Chipp account:

1. Go to [Chipp Settings](https://app.chipp.ai/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:
```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:**
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](https://oauth.net/2/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?

<Callout type="info">
  The Chipp MCP Server does not support static API keys. All authentication uses OAuth.
</Callout>

**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

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `https://app.chipp.ai/api/mcp/oauth/authorize` | GET | Start authorization |
| `https://app.chipp.ai/api/mcp/oauth/token` | POST | Exchange code for tokens |
| `https://app.chipp.ai/api/mcp/oauth/revoke` | POST | Revoke tokens |
| `https://app.chipp.ai/.well-known/oauth-authorization-server` | GET | OAuth discovery |

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

```bash
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

```bash
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](/docs/guides/mcp/rate-limits) - Understanding request limits
- [Tools Reference](/docs/guides/mcp/tools-reference) - All available tools
- [Common Workflows](/docs/guides/mcp/workflows) - Practical examples