# Setup & Installation Connect the Chipp MCP Server to Claude Code, Cursor, or any MCP client --- This guide walks you through connecting the Chipp MCP Server to Claude Code, Cursor, or any custom MCP client by editing a configuration file. > **Note:** **Claude app or Claude Cowork users:** If you use the Claude desktop app or Claude Cowork (not the Claude Code terminal), add Chipp through the connector UI instead. See [Connect from Claude App or Claude Cowork](/docs/guides/mcp/claude-app-cowork). ## Prerequisites - **Studio plan or higher** - MCP access requires a paid subscription ([upgrade here](https://build.chipp.ai/plans)) - **Chipp account** - Sign up at [build.chipp.ai](https://build.chipp.ai) if you haven't already ## Claude Code Claude Code has built-in MCP support. Add Chipp to your configuration file. ### Step 1: Open Configuration The configuration file is located at `~/.claude.json` (your home directory). ```bash # macOS/Linux nano ~/.claude.json # Or open with your preferred editor code ~/.claude.json ``` ### Step 2: Add the Server Add the Chipp server to the `mcpServers` section: ```json { "mcpServers": { "chipp": { "type": "http", "url": "https://build.chipp.ai/mcp" } } } ``` Or let the Claude Code CLI write that entry for you: ```bash claude mcp add --transport http chipp https://build.chipp.ai/mcp ``` **Recommended: add only the Chipp MCPs you need.** The full server sends every Chipp tool (about 157,000 tokens) with each message. Each [Chipp MCP](/docs/guides/mcp/sub-mcps) has its own URL and only its own tools: ```bash claude mcp add --transport http chipp-core https://mcp.chipp.ai/mcp/core claude mcp add --transport http chipp-knowledge https://mcp.chipp.ai/mcp/knowledge ``` Claude Code reads the transport from `"type": "http"`. A `"transport": "streamable-http"` key is not part of its config format, so a server entry that uses it does not connect. If you already have other MCP servers configured: ```json { "mcpServers": { "existing-server": { "...": "..." }, "chipp": { "type": "http", "url": "https://build.chipp.ai/mcp" } } } ``` ### Step 3: Restart Claude Code Close and reopen Claude Code for the changes to take effect. ### Step 4: Authenticate The first time you use a Chipp tool, Claude Code will: 1. Open your browser to the Chipp authorization page 2. Ask you to log in (if not already logged in) 3. Show the permissions being requested - **Read permissions** (viewing apps, knowledge, actions, etc.) are **pre-checked** - **Write permissions** (creating/editing/deleting apps, etc.) are **unchecked by default** - check these only if you need them 4. Click **Authorize** to proceed 5. Return an authorization code to Claude Code After authorization, your tokens are stored securely and refreshed automatically. ### Step 5: Verify Connection Ask Claude to list your apps: ``` List all my Chipp apps ``` You should see a list of your applications. If you see an error, check the [Troubleshooting](#troubleshooting) section. ### Step 6: Request Write Access (if needed) By default, your connection has **read-only permissions**. If you need to create or modify apps: Write tools (such as `create_app`) do not appear in Claude's tool list until your token has the matching write scope. To add write access, disconnect and reconnect: 1. Disconnect: `rm -rf ~/.claude/mcp-auth/chipp*` 2. Restart Claude Code 3. On the first tool call, the authorization screen will show both read and write permissions 4. Check the write permissions you need before authorizing --- ## Cursor Cursor supports MCP through its settings panel. ### Step 1: Open Settings 1. Open Cursor 2. Go to **Settings** (Cmd/Ctrl + ,) 3. Search for "MCP" or navigate to the MCP section ### Step 2: Add Server Add a new MCP server with these settings: | Field | Value | |-------|-------| | Name | `chipp` | | URL | `https://build.chipp.ai/mcp` | | Transport | `streamable-http` | Or add directly to your Cursor settings JSON: ```json { "mcp": { "servers": { "chipp": { "url": "https://build.chipp.ai/mcp", "transport": "streamable-http" } } } } ``` ### Step 3: Authenticate When you first use Chipp tools, Cursor will prompt you to authorize via your browser. --- ## Generic MCP Client For any MCP-compatible client, use these connection details: ### Server Configuration ```json { "name": "chipp", "url": "https://build.chipp.ai/mcp", "transport": "streamable-http" } ``` ### OAuth Discovery The server supports OAuth discovery via: ``` GET https://build.chipp.ai/.well-known/oauth-authorization-server ``` Response: ```json { "issuer": "https://build.chipp.ai", "authorization_endpoint": "https://build.chipp.ai/mcp/oauth/authorize", "token_endpoint": "https://build.chipp.ai/mcp/oauth/token", "registration_endpoint": "https://build.chipp.ai/mcp/oauth/register", "revocation_endpoint": "https://build.chipp.ai/mcp/oauth/revoke", "response_types_supported": ["code"], "grant_types_supported": ["authorization_code", "refresh_token"], "code_challenge_methods_supported": ["S256"], "token_endpoint_auth_methods_supported": ["none"] } ``` ### Manual OAuth Flow If your client doesn't support automatic OAuth, implement the flow manually: 1. **Generate PKCE challenge** (S256 method required) 2. **Redirect to authorize** (with `scope=*` for all permissions): ``` https://build.chipp.ai/mcp/oauth/authorize? client_id=your_client_id &redirect_uri=your_callback_url &response_type=code &scope=* &code_challenge=YOUR_CHALLENGE &code_challenge_method=S256 &state=random_state ``` **Note:** Even with `scope=*`, the consent screen shows write permissions as unchecked by default. The user must explicitly check write scopes to grant them. 3. **Exchange code for tokens**: ```bash POST https://build.chipp.ai/mcp/oauth/token Content-Type: application/json { "grant_type": "authorization_code", "code": "AUTH_CODE", "redirect_uri": "your_callback_url", "client_id": "your_client_id", "code_verifier": "YOUR_VERIFIER" } ``` 4. **Use access token** in requests: ``` Authorization: Bearer chipp_at_xxxxx ``` See the [Authentication Guide](/docs/guides/mcp/authentication) for complete details. --- ## Alternative: API Keys For automation and scripts, you can use API keys instead of OAuth: 1. Go to **Settings > Developer > API Keys** in your Chipp dashboard 2. Click **Create Key** and give it a name 3. Copy the key (shown only once) 4. Use it in your requests: ```json { "mcpServers": { "chipp": { "type": "http", "url": "https://build.chipp.ai/mcp", "headers": { "Authorization": "Bearer chipp_sk_xxxxx" } } } } ``` See the [Authentication Guide](/docs/guides/mcp/authentication#api-keys) for more details on API key management. --- ## Endpoints Reference | Endpoint | Purpose | |----------|---------| | `https://build.chipp.ai/mcp` | Main MCP endpoint (POST JSON-RPC) | | `https://build.chipp.ai/health` | Health check | | `https://build.chipp.ai/.well-known/oauth-authorization-server` | OAuth discovery | | `https://build.chipp.ai/mcp/oauth/authorize` | OAuth authorization | | `https://build.chipp.ai/mcp/oauth/token` | Token exchange | | `https://build.chipp.ai/mcp/oauth/register` | Dynamic client registration | | `https://build.chipp.ai/mcp/oauth/revoke` | Token revocation | --- ## Troubleshooting ### "MCP server not found" **Cause**: Configuration file not loaded or syntax error. **Fix**: 1. Verify JSON syntax (use a JSON validator) 2. Check the config file path is correct 3. Restart your MCP client ### "Authentication required" **Cause**: No valid token or token expired. **Fix**: 1. Trigger a tool call to start OAuth flow 2. Complete authorization in browser 3. If flow fails, clear cached tokens and retry ### "Connection refused" **Cause**: Network issue or server URL typo. **Fix**: 1. Verify URL: `https://build.chipp.ai/mcp` 2. Check internet connection 3. Try the health endpoint: `curl https://build.chipp.ai/health` ### "Invalid scope" or write tools not available **Cause**: Either an invalid scope name was used, or write scopes weren't selected during authorization. **Fix**: 1. If you see write tools missing (like `create_app`), your token is read-only. Reconnect or reauthorize: - On the consent screen, **check the write permissions you need** (e.g., "Manage your apps" for `apps:write`) - Click Authorize 2. If you see an actual scope error, verify you're using valid scope names: - Valid: `apps:read`, `apps:write`, `knowledge:read`, `knowledge:write`, etc. - `scope=*` is valid and will show all permissions (but you must still select write scopes on the consent screen) ### "Rate limit exceeded" **Cause**: Too many requests for your subscription tier. **Fix**: 1. Wait for the reset time (check `Retry-After` header) 2. Consider upgrading your plan for higher limits 3. See [Rate Limits Guide](/docs/guides/mcp/rate-limits) for best practices ### Clearing Cached Tokens If you need to re-authenticate: **Claude Code**: ```bash # Find and remove Chipp tokens rm -rf ~/.claude/mcp-tokens/chipp* ``` **Cursor**: - Go to Settings > MCP > Chipp > Remove/Reconnect --- ## Testing Your Connection After setup, verify everything works with these commands: ### Basic Test ``` "List my Chipp apps" ``` Expected: A list of your applications with IDs and names. ### Permission Test ``` "Create a test app called MCP-Test with a simple greeting prompt" ``` Expected: App created successfully with ID returned. ### Cleanup ``` "Delete the app named MCP-Test" ``` Expected: App deleted confirmation. > **Success:** If all three tests pass, you're ready to use the full power of the Chipp MCP Server! ## Next Steps - [Authentication](/docs/guides/mcp/authentication) - Deep dive into OAuth and API keys - [Tools Reference](/docs/guides/mcp/tools-reference) - All available tools - [Common Workflows](/docs/guides/mcp/workflows) - Step-by-step examples