Next liveBuild Your Own Calendly · zoomwithchipp.comSave your seat →
Developer Platform

Authentication

How authentication works when connecting MCP clients to your Chipp account

|View as Markdown
1 min read
#mcp#oauth#authentication#security#pkce#api-keys

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:

  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:

  • The name of the app requesting access (for example, Claude Code)
  • The organization and workspace you are granting access to
  • Requested permissions (read permissions pre-checked, write permissions unchecked)
  • 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 TypePrefixLifetimeWhat It Does
Access Tokenchipp_at_1 hourAuthenticates each request
Refresh Tokenchipp_rt_30 daysGets 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

  1. Go to Settings > API Keys in your Chipp dashboard
  2. Click Create Key and give it a descriptive name
  3. Optionally set an expiration (30 days, 90 days, 1 year, or never)
  4. Choose the key’s Workspace: All workspaces (org-wide) (the default) or one workspace. See Workspace-bound keys.
  5. Choose the key’s Access: Full access (the default, every scope), Read only (every read scope, no write scopes), or Custom (check the exact scopes the key needs, see Operation scopes). For least privilege, pick the narrowest workspace and access level that works.
  6. 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": {
      "type": "http",
      "url": "https://build.chipp.ai/mcp",
      "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 can be bound to one workspace, so a leaked key cannot reach the rest of your organization
  • 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 operation scopes. In Settings > API Keys, choose Custom access to see one checkbox per scope. Write scopes carry a Write badge.

ScopeCheckbox labelWhat It AllowsWrite (destructive)?
apps:readView your appsSee app configurations, settings, and prompts-
apps:writeManage your appsCreate, update, and delete apps, including system prompt edits✓ Opt-in
knowledge:readView knowledge sourcesAccess uploaded documents and training data-
knowledge:writeManage knowledgeUpload, update, and delete knowledge sources✓ Opt-in
actions:readView custom actionsSee API integrations and action configurations-
actions:writeManage custom actionsCreate, update, and delete API integrations✓ Opt-in
components:readView custom componentsSee custom UI components (Component Studio)-
components:writeManage custom componentsCreate, update, delete, and share custom UI components✓ Opt-in
workspace:readView workspaceSee workspace settings, members, and organization info-
workspace:writeManage workspacesCreate and update workspaces in your organization✓ Opt-in
billing:readView billing infoSee subscription status and usage-
analytics:readView analyticsAccess conversation history and usage statistics-
analytics:writeLog conversationsPush external chat turns into the Conversations tab (n8n, Zapier, custom pipelines)✓ Opt-in
agents:chatChat with agentsSend messages to your hosted agents over their own MCP endpoint (/mcp/agents/<appId>). The agent decides what to do and can use its own tools-
*Full accessAll permissions (API keys only)-

A write scope also grants the matching read scope. A key with only agents:chat can talk to a hosted agent and cannot call any other tool on the Chipp MCP server.

What a key reports in the key list

Each key in Settings > API Keys shows a reach label: where the key works, and what it may do.

LabelMeaning
Org-wide: all workspaces, all operationsNot bound to a workspace, with Full access.
Org-wide: all workspaces, read onlyNot bound to a workspace, with read scopes only.
Workspace: <name> only, all operationsBound to that workspace, with Full access.
Workspace: <name> only, read onlyBound to that workspace, with read scopes only.
Workspace: <name> only, 3 scopesBound to that workspace, with a custom set that includes at least one write scope (the number is the scope count).

The key’s scopes also show as pills under the label.

Existing keys do not change. A key created before workspace-bound keys existed stays org-wide with all operations. To narrow it, create a new key with the workspace and scopes you want, switch your automation to it, then revoke the old key.

Workspace-bound keys

When you create a key, the Workspace field offers All workspaces (org-wide) or one workspace of your organization. You can only bind a key to a workspace you belong to (organization owners and admins can bind to any workspace in the organization). A key can never reach more than the person who created it can.

A key always belongs to your own organization. If you also work in a client’s organization and are viewing it, the Workspace field still lists only your own organization’s workspaces. To make a key for the client’s organization, someone whose account belongs to that organization creates it.

A key bound to one workspace behaves like this:

  • create_app puts the new app in the bound workspace when you leave workspace_id out. If you pass a different workspace, the call is refused.
  • Apps and sub-resources (knowledge sources, tags, evals, sessions, components, and so on) outside the bound workspace are refused, the same as if they did not exist.
  • List and search tools (list_apps, search_apps, list_workspaces) return only the bound workspace and its apps.
  • Organization-level tools are not available. This covers billing and usage, creating workspaces, newsletters, Slack installations, action collections, and tools that rank or search agents across the organization. They are hidden from tools/list and refused if called.
  • Software factory tools are not available. The Software Factory Tickets tools work on the whole organization, so a bound key cannot use them.
  • Deleting the workspace deletes the key. A bound key never turns into an org-wide key.

A call outside the bound workspace is refused with an error like this:

plaintext
Access denied: this API key is restricted to one workspace, and this resource is not in it
(or does not exist). Use a resource in the key's workspace, or ask an organization owner or
admin for a key with the reach you need (Settings > API Keys).

When a scope is missing

If a tool needs a scope the key does not have, the tool is left out of tools/list. Calling it anyway is refused with a JSON-RPC -32602 error that names the scope:

plaintext
Unknown tool: create_app. It needs the "apps:write" scope, which this credential does not have.
Create a key with that scope (Settings > API Keys).

Create a new key with that scope. A key’s scopes cannot be edited after creation.

Write scopes are opt-in by default

By design, new OAuth connections receive read-only permissions by default. Write scopes (marked “Opt-in” above) are never granted unless you explicitly request them on the authorization screen. This prevents accidental or excessive permissions.

When you first connect or reconnect your MCP client:

  1. The consent screen shows one list of permissions: read permissions are pre-checked, and write permissions are unchecked and marked Destructive
  2. Check any write permission you need before clicking Authorize
  3. Your new token will include only the permissions you explicitly selected

Reauthorization: If you already have a read-only connection and need write access later, disconnect and reconnect your MCP client, then check the write permissions on the consent screen. You don’t need to generate a new API key or switch authentication methods. An existing token never gains a permission on its own: it keeps the scopes it was issued with until you reconnect.

What discovery advertises: The OAuth discovery documents (/.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/... on both build.chipp.ai and mcp.chipp.ai) list every concrete scope in scopes_supported, read and write, never *. Clients that build their scope request from this list (Claude Enterprise organization connectors, for example) can then offer every write permission on the consent screen. Listing a scope there does not grant it: write permissions still start unchecked, and your token includes only what you check.

Scopes are a ceiling, not a grant

A token scope says what the credential is allowed to attempt. What you can actually do is still bounded by your workspace permissions — the role (OWNER / EDITOR / VIEWER) and any per-member permission overrides your organization owner configured in the dashboard.

MCP enforces exactly the same permissions as the Chipp web app. A token with apps:write held by a workspace VIEWER cannot change that workspace’s apps, and an API key never grants more access than the person who created it has. If a tool is refused for this reason, the error tells you which permission is missing and what to ask for, for example:

plaintext
Permission denied: this operation requires 'write' access to 'System prompt' in the
workspace that owns this app. Your workspace role currently grants 'read' on 'System
prompt'. Ask your organization owner or an admin to elevate your role (OWNER or EDITOR)
or grant you write access to 'System prompt' for this workspace
(Settings > Workspace > Members > your user > permissions).

Reading is unaffected: workspace members (including VIEWERs) keep read access to the apps in their workspaces. Organization owners and admins have full access to every workspace in their organization.


Revoking Access

Revoking OAuth Tokens

To disconnect an MCP client from your Chipp account, go to Settings > Developer > Connected Apps and revoke it there, or 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 > API Keys in your Chipp dashboard, click the trash icon next to the key you want to revoke, then click Revoke Key to confirm. 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:

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

Write tools are missing, or “Unknown tool”

What happened: The tool requires a permission that wasn’t granted. Tools your token lacks the scope for are left out of the tool list, and calling one returns an Unknown tool error that names the missing scope (for example It needs the "apps:write" scope). For a workspace-bound key, organization-level tools are also left out; see Workspace-bound keys. This commonly occurs with write tools (apps:write, knowledge:write, etc.) when you first connect.

Why it happens: By default, new OAuth connections grant read-only permissions only. Write access (like creating or deleting apps) is opt-in to prevent accidental permissions. You can request write permissions explicitly during authorization. Connections made before November 2026 from a Claude Enterprise organization connector could only be offered View permissions; reconnect them to see the write options.

Fix: Reconnect or reauthorize with write permissions selected:

  1. Disconnect your current Chipp connection (or revoke the OAuth token below)
  2. Reconnect: your MCP client will re-initiate the OAuth flow
  3. On the consent screen, you’ll see checkboxes for permissions including write tools
  4. Check the write permissions you need (e.g., “Manage your apps” for apps:write)
  5. Click Authorize
  6. After reconnection, your MCP client will have the write tools available

”Permission denied: this operation requires ‘write’ access to …”

What happened: Your token had the right scope, but your workspace permissions do not allow this change. This is the same check the Chipp web app applies, so you would see the control disabled (or absent) in the dashboard too.

Fix: Ask your organization owner or an admin to either change your workspace role to EDITOR or OWNER, or grant you write access to the specific permission named in the error (Settings > Workspace > Members > your user). The change takes effect immediately, with no need to re-authorize or mint a new key. See Scopes are a ceiling, not a grant.

”Access denied: this API key is restricted to one workspace …”

What happened: The key is bound to one workspace, and the app, workspace, or other resource in your call is outside it (or does not exist).

Fix: Use a resource in the key’s workspace. If the key needs wider reach, ask an organization owner or admin for an org-wide key or a key bound to the right workspace. See Workspace-bound keys.

”Access denied: you are not a member of the workspace …”

What happened: The app you targeted lives in a workspace you do not belong to. An API key never grants more access than the person who created it, so this happens even when the app is in your organization.

Fix: Ask your organization owner or an admin to add you to that workspace, or to grant you owner/admin on the organization (which carries access to every workspace in it).

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:

  • 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 refresh token and issues a new pair. The previous access token stays valid for 30 seconds so in-flight requests do not fail. 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

EndpointMethodPurpose
https://build.chipp.ai/mcp/oauth/authorizeGETStart authorization
https://build.chipp.ai/mcp/oauth/tokenPOSTExchange code for tokens
https://build.chipp.ai/mcp/oauth/registerPOSTDynamic client registration
https://build.chipp.ai/mcp/oauth/revokePOSTRevoke tokens
https://build.chipp.ai/.well-known/oauth-authorization-serverGETOAuth 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