Prerequisites
You’ll need your Swoogo API credentials (consumer key and secret) from My Profile > API Credentials in Swoogo.Connect your client
- Claude Desktop
- Claude Code
- Cursor
Authorize
Claude Desktop will open a browser window. Enter your Swoogo API consumer key and secret to authorize access.
Authentication
The MCP server supports two authentication modes:OAuth 2.0 (recommended)
Used by Claude Desktop, Cursor, and other GUI-based MCP clients. The server implements OAuth 2.0 Authorization Code with PKCE (RFC 7636):- Your MCP client discovers the OAuth endpoints via
/.well-known/oauth-authorization-server - You authorize in the browser by entering your Swoogo API credentials
- The server issues encrypted access and refresh tokens
- Tokens are automatically refreshed — no manual re-authentication needed
Access tokens expire after 1 hour and are automatically refreshed. Refresh tokens are valid for 30 days.
Bearer token (CLI / scripts)
For programmatic access or CLI-based MCP clients:- Base64-encode your credentials:
base64(consumer_key:consumer_secret) - Send as a Bearer token in the Authorization header
Common parameters
Most read tools share these optional parameters:| Parameter | Description |
|---|---|
fields | Comma-separated list of fields to return |
expand | Include related objects (e.g., sessions, contact) |
search | Raw Swoogo search filter (e.g., status=confirmed) |
page | Page number (default: 1) |
per_page | Results per page (default: 20, max: 100) |
sort | Sort field, prefix with - for descending |
Error handling
The server returns helpful error messages with recovery hints:| Error | Meaning | Recovery |
|---|---|---|
401 | Credentials expired | Re-authorize via your MCP client |
404 | Resource not found | Verify the ID exists |
422 | Validation failed | Check required fields — call swoogo_get_registration_form for field details |
429 | Rate limited | Wait and retry — the response includes the wait time |