Skip to main content
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: 
export SNACKBASE_URL="https://your-snackbase-instance.com"
For local development, use: http://localhost:8000

​
API Key

Your API key for authentication: 
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: 
export SNACKBASE_ACCOUNT_ID="your-account-id"
If not specified, the MCP server will use the API key’s default account.

​
Timeout

Request timeout in milliseconds (default: 30000ms): 
export SNACKBASE_TIMEOUT=60000  # 60 seconds

​
Debug Mode

Enable debug logging for troubleshooting: 
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

# .env for local development
SNACKBASE_URL=http://localhost:8000
SNACKBASE_API_KEY=your-dev-api-key
SNACKBASE_DEBUG=true

​
Production (Self-Hosted)

SNACKBASE_URL=https://api.example.com
SNACKBASE_API_KEY=sb_ak.xxx.xxx
SNACKBASE_TIMEOUT=60000

​
SnackBase Cloud

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: 
{
  "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: 
{
  "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"
      }
    }
  }
}
Don’t commit API keys to version control. Use different API keys for different environments and rotate them regularly.

​
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

{
  "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:
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: 
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: 
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