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

# Setup

> Connect your AI assistant to Swoogo via the MCP server

## Prerequisites

You'll need your Swoogo API credentials (consumer key and secret) from **My Profile > API Credentials** in Swoogo.

## Connect your client

<Tabs>
  <Tab title="Claude Desktop">
    <Steps>
      <Step title="Add the server">
        Open Claude Desktop settings and add the Swoogo MCP server URL:

        ```
        https://mcp.swoogo.com
        ```
      </Step>

      <Step title="Authorize">
        Claude Desktop will open a browser window. Enter your Swoogo API consumer key and secret to authorize access.
      </Step>

      <Step title="Start using tools">
        The Swoogo tools will appear in Claude Desktop. Try asking: *"Show me my upcoming events"*
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code">
    <Steps>
      <Step title="Add the server">
        Add the Swoogo MCP server to your Claude Code configuration:

        ```bash theme={null}
        claude mcp add swoogo https://mcp.swoogo.com
        ```
      </Step>

      <Step title="Authorize">
        Follow the OAuth flow in your browser when prompted, entering your Swoogo API consumer key and secret.
      </Step>

      <Step title="Start using tools">
        Swoogo tools are now available. Try: *"List all sessions for event 12345"*
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Add the server">
        In Cursor's MCP settings, add a new server with the URL:

        ```
        https://mcp.swoogo.com
        ```
      </Step>

      <Step title="Authorize">
        Complete the OAuth flow in the browser window that opens, entering your Swoogo API credentials.
      </Step>

      <Step title="Start using tools">
        Swoogo tools are now available in your AI assistant panel.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## 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):

1. Your MCP client discovers the OAuth endpoints via `/.well-known/oauth-authorization-server`
2. You authorize in the browser by entering your Swoogo API credentials
3. The server issues encrypted access and refresh tokens
4. Tokens are automatically refreshed — no manual re-authentication needed

<Info>Access tokens expire after **1 hour** and are automatically refreshed. Refresh tokens are valid for **30 days**.</Info>

### Bearer token (CLI / scripts)

For programmatic access or CLI-based MCP clients:

1. Base64-encode your credentials: `base64(consumer_key:consumer_secret)`
2. Send as a Bearer token in the Authorization header

```bash theme={null}
# Encode your credentials
echo -n "YOUR_KEY:YOUR_SECRET" | base64
```

The server exchanges this for a Swoogo API token on each request and caches it until expiry.

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