# MCP Tools Reference

CompactSaaS MCP server provides 54 tools for managing your account via AI assistants (Kiro, Cursor, Claude Desktop, Codex).

## Quick Start

Add this to your MCP client configuration:

```json
{
  "mcpServers": {
    "compactsaas": {
      "url": "https://mcp.compactsaas.com/v1/mcp"
    }
  }
}
```

Your MCP client will open a browser for login. No API keys needed.

## Read Tools (31)

| Tool | Parameters | Description |
|------|-----------|-------------|
| `list-websites` | — | List all analytics websites configured for your account |
| `get-website` | `websiteId` | Get details of a specific analytics website |
| `find-orphans` | — | Find analytics websites whose underlying short link / redirect / bio page no longer exists. These are safe to delete — the source resource was removed but the analytics website was left behind. Returns websiteId, sourceType, why, and suggested next step. |
| `list-redirects` | — | List all URL redirects configured for your account. Shows source domain/path, target URL, status code, and enabled state. |
| `list-short-links` | — | List all short links for your account. Shows short code, domain, target URL, and click status. |
| `list-api-keys` | — | List active API keys for your account. Shows key prefix (first 8 chars), name, and last used timestamp. Full key values are never exposed. |
| `list-domains` | — | List custom domains and their verification/activation status. Shows DNS verification state and tenant provisioning status. |
| `estimate-cost` | `pageviews`, `events`, `clicks`, `links`, `domains`, `mcpUsers` | Estimate monthly cost based on usage. Provide any combination of: pageviews, events, clicks, links, domains, mcpUsers. Returns per-meter breakdown and total. |
| `get-account-info` | — | Get your CompactSaaS account information and the live list of MCP tools registered on this server. |
| `get-website-stats` | `websiteId`, `startDate`, `endDate` | Get analytics stats for a website — pageviews, sessions, bounce rate, visit duration. Specify date range with startDate/endDate (ISO format). |
| `get-website-timeseries` | `websiteId`, `startDate`, `endDate`, `unit` | Get time series analytics data for charts. Returns data points over the date range. |
| `get-website-breakdown` | `websiteId`, `startDate`, `endDate`, `field` | Get analytics breakdown by dimension — top pages, referrers, browsers, countries, devices, OS. Use field parameter: page, referrer, browser, country, device, os. |
| `get-website-realtime` | `websiteId` | Get real-time visitor count for a website. |
| `list-qr-codes` | — | List all QR codes for your account. |
| `get-qr-code` | `qrId` | Get details and rendered image of a specific QR code. Returns metadata plus the QR code as a PNG image. |
| `list-qr-presets` | — | List QR code style presets for your account. |
| `get-link-detail` | `linkId` | Get full details of a specific link (redirect or short link) including analytics. If the ID belongs to a different resource type (website, bio page, wallet pass) the response includes a suggested tool to use instead. |
| `get-usage-summary` | — | Get current month usage summary — meter readings and estimated costs. |
| `list-team-members` | — | List members of your team. |
| `get-website-stats-compare` | `websiteId`, `startDate`, `endDate` | Compare analytics stats between two periods — shows current vs previous with percentage change. Great for week-over-week or month-over-month analysis. |
| `get-website-events` | `websiteId`, `startDate`, `endDate` | Get distinct custom event names tracked on a website for a date range. |
| `list-qr-images` | — | List images in your QR code image library — logos and icons for QR customization. |
| `get-usage-history` | — | Get past usage billing records — shows what you were billed for in previous months. |
| `list-wallet-passes` | — | List all Apple Wallet passes for the team. Each pass has a tracked short link for analytics. Event-tracked passes include event metadata and landing override. |
| `get-wallet-pass` | `passId` | Get details of a specific Apple Wallet pass including its tracked short link, full configuration, and event metadata if it is an event-tracked pass. |
| `list-bio-pages` | — | List all bio pages (link-in-bio) for your account. |
| `get-bio-page` | `pageId` | Get a specific bio page by ID — includes title, bio, links, social links, theme, and tracked short URL. |
| `list-bio-event-passes` | `pageId` | List all event-tracked wallet passes for a bio page. Returns event metadata, short URLs, and per-event analytics website IDs so you can query scan counts. |
| `list-bio-event-templates` | `pageId` | List saved event templates for a bio page. Templates store reusable landing overrides for recurring event types (e.g. "Standard tech conference"). |
| `request-bio-image-upload` | `contentType`, `name`, `maxBytes` | Request a presigned S3 PUT URL for uploading a bio page avatar image. Returns an imageId to reference from create-bio-page or update-bio-page once the PUT completes. Use this to attach photos without round-tripping bytes through this MCP server. Allowed types: image/png, image/jpeg, image/webp, image/gif. Max 5 MB by default. |
| `get-bio-image-url` | `imageId` | Compute the public CloudFront URL for an uploaded bio image. Useful for verifying an upload landed correctly or for embedding in external content. |

## Write Tools (21)

| Tool | Parameters | Description |
|------|-----------|-------------|
| `create-website` | `name`, `domain` | Create a new analytics website to track a site you own. Returns the websiteId and a ready-to-paste tracking snippet. Events are ingested at https://track.<domain>/send and the script is served from https://<domain>/analytics/script.js. All websites are advanced tier. Note: short links, redirects and bio pages auto-create their own analytics website — use this only to track a standalone external site. |
| `delete-website` | `websiteId` | Soft-delete an analytics website. Starts a 7-day grace period before analytics data is purged — the website can be restored within that window via admin tools. Use find-orphans to discover websites whose source link/page no longer exists. |
| `create-short-link` | `targetUrl`, `customCode`, `domain` | Create a new short link. Optionally specify a `domain` — either one of the platform short domains (call list-platform-short-domains to see options) or a verified custom domain on your team. Returns the short URL, link ID, and a dashboard URL for further editing. |
| `update-short-link` | `linkId`, `targetUrl`, `analyticsEnabled` | Update a short link — change target URL or analytics setting. |
| `delete-short-link` | `linkId` | Permanently delete a short link. This cannot be undone — the short URL will stop working. |
| `create-redirect` | `sourceDomain`, `sourcePath`, `targetUrl`, `statusCode` | Create a URL redirect. Traffic to sourceDomain/sourcePath will be redirected to targetUrl. |
| `update-redirect` | `redirectId`, `targetUrl`, `statusCode`, `enabled` | Update a redirect — change target URL, status code, or enable/disable it. |
| `delete-redirect` | `redirectId` | Permanently delete a redirect. This cannot be undone — the redirect will stop working. |
| `create-api-key` | `name` | Create a new API key. IMPORTANT: The full key is only shown once in this response — save it immediately. Max 2 keys per team. |
| `revoke-api-key` | `keyId` | Permanently revoke an API key. This cannot be undone — any integrations using this key will stop working. |
| `create-qr-code` | `name`, `sourceUrl` | Create a new QR code for a URL. Response includes a dashboardUrl for entering the QR design studio. |
| `delete-qr-code` | `qrId` | Permanently delete a QR code. This cannot be undone. |
| `create-wallet-pass` | `name`, `style`, `description`, `logoText`, `primaryLabel`, `primaryValue`, `barcodeData`, `backgroundColor`, `foregroundColor`, `shareDomain` | Create an Apple Wallet pass. Auto-creates a tracked short link for analytics — pass `shareDomain` to use a verified custom domain instead of the default urlz.zip. Styles: generic, coupon, eventTicket, storeCard, boardingPass. Response includes a billing block (each pass is metered at $0.03) and a dashboardUrl for attaching a custom logo image. |
| `delete-wallet-pass` | `passId` | Permanently delete an Apple Wallet pass. This cannot be undone. The tracked short link is NOT deleted. |
| `verify-domain` | `domain` | Start domain verification. Returns DNS records you need to add and a dashboardUrl for the domain settings page. After adding the records, use activate-domain. |
| `activate-domain` | `domain` | Activate a verified domain. DNS must be verified first via verify-domain. |
| `create-bio-page` | `title`, `bio`, `published`, `domain`, `customCode`, `avatarImageId`, `links`, `shortLinkId`, `title`, `thumbnailImageId`, `visible` | Create a new bio page (link-in-bio). Auto-creates a tracked short link for sharing. Max 10 per team. Accepts the same theme/links/socials/avatar fields as update-bio-page so a fully populated page can be created in a single call. Pass `dryRun: true` to validate the input shape against the schema without persisting (returns the input echoed back with `dryRun: true` and a synthetic id). |
| `update-bio-page` | `pageId`, `title`, `bio`, `published`, `avatarImageId`, `links`, `shortLinkId`, `title`, `thumbnailImageId`, `visible` | Update a bio page — change title, bio text, published state, links, social links, theme, or attached avatar image. |
| `delete-bio-page` | `pageId` | Delete a bio page and its associated short link and analytics website |
| `create-bio-event-pass` | `pageId`, `eventName`, `eventDate`, `eventLocation`, `eventOrganizer`, `overrideTitle`, `overrideBio`, `visibleLinkIds` | Create an event-tracked wallet pass for a bio page. Each event gets its own tracked short link (for per-event scan analytics) and an optional landing page override (custom title/bio/visible links shown only when visitors arrive via this pass). Use this for conferences, meetups, or any event where you want to segment engagement. |
| `delete-bio-image` | `imageId` | Delete an uploaded bio page avatar image from storage. Note: this does NOT detach it from any bio page — call update-bio-page with avatarImageId="" first if the image is in use. |

## Documentation Tools (2)

| Tool | Parameters | Description |
|------|-----------|-------------|
| `search-docs` | `query` | Search CompactSaaS documentation. Uses OR-match scoring with synonyms (e.g. "avatar" matches docs containing "profile", "photo", or "logo"). Pages are returned ranked by relevance — most-matching pages first. Use read-doc to fetch a specific page. If you get zero results, try fewer or different terms. |
| `read-doc` | `docId` | Read a CompactSaaS documentation page by ID. Use search-docs first to find the right page. Returns the raw content from the live documentation. If the live URL returns the SPA fallback (a known failure mode for missing docs), the tool detects this and returns a structured error with the fetched content type. |

## Authentication

OAuth 2.1 with your existing CompactSaaS account. Browser-based login with MFA support. Sessions last 30 days via refresh token. Your access is scoped to your team.

## Pricing

$1 per active MCP user per month. Only users who connect in a given month are counted.

*Generated at build time from 54 tool definitions.*