> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snackbase.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure the SnackBase MCP server for your needs

The SnackBase MCP server uses environment variables for configuration. This guide covers all available options.

## Required Configuration

### Base URL

The URL of your SnackBase backend instance:

```bash theme={null}
export SNACKBASE_URL="https://your-snackbase-instance.com"
```

<Note>
  For local development, use: `http://localhost:8000`
</Note>

### API Key

Your API key for authentication:

```bash theme={null}
export SNACKBASE_API_KEY="sb_ak.payload.signature"
```

The API key format is `sb_ak.<payload>.<signature>` where:

* `sb_ak` identifies this as a SnackBase API key
* `payload` contains encoded metadata (account, permissions, expiry)
* `signature` verifies the key's authenticity

## Optional Configuration

### Account ID (Multi-Tenant)

If your API key has access to multiple accounts, specify which one to use:

```bash theme={null}
export SNACKBASE_ACCOUNT_ID="your-account-id"
```

<Note>
  If not specified, the MCP server will use the API key's default account.
</Note>

### Timeout

Request timeout in milliseconds (default: 30000ms):

```bash theme={null}
export SNACKBASE_TIMEOUT=60000  # 60 seconds
```

### Debug Mode

Enable debug logging for troubleshooting:

```bash theme={null}
export SNACKBASE_DEBUG=true
```

This will log additional information to stderr, including:

* Incoming tool calls
* SDK requests
* Response times
* Error details

## Configuration Examples

### Local Development

```bash theme={null}
# .env for local development
SNACKBASE_URL=http://localhost:8000
SNACKBASE_API_KEY=your-dev-api-key
SNACKBASE_DEBUG=true
```

### Production (Self-Hosted)

```bash theme={null}
SNACKBASE_URL=https://api.example.com
SNACKBASE_API_KEY=sb_ak.xxx.xxx
SNACKBASE_TIMEOUT=60000
```

### SnackBase Cloud

```bash theme={null}
SNACKBASE_URL=https://api.snackbase.dev
SNACKBASE_API_KEY=sb_ak.xxx.xxx
```

## Claude Code Configuration

To use the MCP server with Claude Code, add it to your Claude configuration:

### Locate Your Config

The Claude Code configuration file is at:

* **macOS/Linux**: `~/.claude/settings.json`
* **Windows**: `%APPDATA%\claude\settings.json`

### Add MCP Server

Add the MCP server to the `mcpServers` section:

```json theme={null}
{
  "mcpServers": {
    "snackbase": {
      "command": "snackbase-mcp",
      "args": [],
      "env": {
        "SNACKBASE_URL": "https://your-snackbase-instance.com",
        "SNACKBASE_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Multiple Instances

If you need to connect to multiple SnackBase instances:

```json theme={null}
{
  "mcpServers": {
    "snackbase-dev": {
      "command": "snackbase-mcp",
      "args": [],
      "env": {
        "SNACKBASE_URL": "http://localhost:8000",
        "SNACKBASE_API_KEY": "dev-api-key"
      }
    },
    "snackbase-prod": {
      "command": "snackbase-mcp",
      "args": [],
      "env": {
        "SNACKBASE_URL": "https://api.example.com",
        "SNACKBASE_API_KEY": "prod-api-key"
      }
    }
  }
}
```

<Warning>
  Don't commit API keys to version control. Use different API keys for different environments and rotate them regularly.
</Warning>

## Cursor Configuration

For Cursor IDE, the configuration is similar but in a different location:

### Locate Your Config

* **macOS/Linux**: `~/.cursor/settings.json`
* **Windows**: `%APPDATA%\cursor\settings.json`

### Add MCP Server

```json theme={null}
{
  "mcpServers": {
    "snackbase": {
      "command": "snackbase-mcp",
      "args": [],
      "env": {
        "SNACKBASE_URL": "https://your-snackbase-instance.com",
        "SNACKBASE_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Troubleshooting

### Connection Errors

If you see connection errors:

1. **Verify the URL** is correct and accessible
2. **Check your API key** is valid and not expired
3. **Ensure the backend is running** (for self-hosted)
4. **Test with curl**:

```bash theme={null}
curl -H "X-API-Key: $SNACKBASE_API_KEY" \
     "$SNACKBASE_URL/api/v1/health"
```

### Permission Errors

If you get permission errors:

1. **Verify the API key** has the required permissions
2. **Check the account** the API key belongs to
3. **Review collection rules** if accessing specific collections

### Debug Mode

Enable debug mode to see detailed logs:

```bash theme={null}
export SNACKBASE_DEBUG=true
snackbase-mcp
```

Look for errors in the stderr output.

## Security Best Practices

### API Key Management

* **Use separate keys** for different environments
* **Rotate keys regularly** (e.g., every 90 days)
* **Use minimal permissions** - only grant what's needed
* **Monitor usage** via audit logs
* **Revoke compromised keys** immediately

### Environment Isolation

* **Never use production keys** in development
* **Use different API keys** for different applications
* **Document key purposes** in key names

### Audit Trail

Monitor MCP server usage via the audit logs:

```typescript theme={null}
import { SnackBaseClient } from '@snackbase/sdk';

const client = new SnackBaseClient({
  baseUrl: 'https://api.example.com',
  apiKey: 'admin-api-key',
});

// Get recent MCP activity
const logs = await client.auditLogs.list({
  filter: { operation: { $in: ['create', 'update', 'delete'] } },
  sort: '-created_at',
  limit: 50
});
```

## Next Steps

* **[Integration Guide](/mcp/integration)** - Use with Claude Code and other clients
* **[Tools Reference](/mcp/tools)** - Detailed documentation for each tool