# 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 your preferred AI coding assistant.

## Prerequisites

- **Pro plan or higher** - MCP access requires a paid subscription ([upgrade here](https://app.chipp.ai/plans))
- **Chipp account** - Sign up at [app.chipp.ai](https://app.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": {
      "url": "https://mcp.chipp.ai/mcp/messages",
      "transport": "http"
    }
  }
}
```

If you already have other MCP servers configured:

```json
{
  "mcpServers": {
    "existing-server": {
      "...": "..."
    },
    "chipp": {
      "url": "https://mcp.chipp.ai/mcp/messages",
      "transport": "http"
    }
  }
}
```

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

---

## 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://mcp.chipp.ai/mcp/messages` |
| Transport | `http` |

Or add directly to your Cursor settings JSON:

```json
{
  "mcp": {
    "servers": {
      "chipp": {
        "url": "https://mcp.chipp.ai/mcp/messages",
        "transport": "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://mcp.chipp.ai/mcp/messages",
  "transport": "http"
}
```

### OAuth Discovery

The server supports OAuth discovery via:

```
GET https://app.chipp.ai/.well-known/oauth-authorization-server
```

Response:
```json
{
  "issuer": "https://app.chipp.ai",
  "authorization_endpoint": "https://app.chipp.ai/api/mcp/oauth/authorize",
  "token_endpoint": "https://app.chipp.ai/api/mcp/oauth/token",
  "revocation_endpoint": "https://app.chipp.ai/api/mcp/oauth/revoke",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256", "plain"]
}
```

### Manual OAuth Flow

If your client doesn't support automatic OAuth, implement the flow manually:

1. **Generate PKCE challenge** (recommended: S256 method)
2. **Redirect to authorize**:
   ```
   https://app.chipp.ai/api/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
   ```
3. **Exchange code for tokens**:
   ```bash
   POST https://app.chipp.ai/api/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.

---

## Endpoints Reference

| Endpoint | Purpose |
|----------|---------|
| `https://mcp.chipp.ai/mcp/messages` | Main MCP endpoint (POST JSON-RPC) |
| `https://mcp.chipp.ai/health` | Health check |
| `https://mcp.chipp.ai/rate-limits` | View rate limit info |
| `https://app.chipp.ai/.well-known/oauth-authorization-server` | OAuth discovery |
| `https://app.chipp.ai/api/mcp/oauth/authorize` | OAuth authorization |
| `https://app.chipp.ai/api/mcp/oauth/token` | Token exchange |
| `https://app.chipp.ai/api/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://mcp.chipp.ai/mcp/messages`
2. Check internet connection
3. Try the health endpoint: `curl https://mcp.chipp.ai/health`

### "Invalid scope"

**Cause**: Requesting unauthorized permissions.

**Fix**:
1. Use `scope=*` for all permissions, or
2. Request only needed scopes (e.g., `apps:read apps:write`)

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

<Callout type="success">
  If all three tests pass, you're ready to use the full power of the Chipp MCP Server!
</Callout>

## Next Steps

- [OAuth Authentication](/docs/guides/mcp/authentication) - Deep dive into tokens and security
- [Tools Reference](/docs/guides/mcp/tools-reference) - All 77 available tools
- [Common Workflows](/docs/guides/mcp/workflows) - Step-by-step examples