# Windsor.ai MCP Server — Full Reference for LLMs

> Windsor.ai MCP Server is a Model Context Protocol (MCP) server that connects
> AI agents and coding assistants to 325+ marketing, advertising, analytics,
> e-commerce, CRM, and database platforms. Query live data from Meta Ads,
> Google Ads, TikTok Ads, LinkedIn Ads, Microsoft Ads, Google Analytics 4,
> HubSpot, Salesforce, Klaviyo, Shopify, Stripe, BigQuery, Snowflake and more.

## Server Endpoints

- MCP (Streamable HTTP): `POST https://mcp.windsor.ai/`
- MCP (SSE): `GET https://mcp.windsor.ai/sse/`
- Health check: `GET https://mcp.windsor.ai/health`
- HTML docs: `GET https://mcp.windsor.ai/docs`
- LLM short summary: `GET https://mcp.windsor.ai/llms.txt`
- LLM full reference: `GET https://mcp.windsor.ai/llms-full.txt`
- Available data sources: `GET https://mcp.windsor.ai/datasources`
- OAuth metadata: `GET https://mcp.windsor.ai/.well-known/oauth-authorization-server`
- Protocol: JSON-RPC 2.0 over HTTP (MCP) or SSE

## Authentication

Bearer tokens in the Authorization header.

### OAuth 2.0 (recommended)

The MCP server implements the full MCP OAuth flow via FastMCP's OAuth proxy.
Clients that support MCP OAuth — including Claude, ChatGPT, Cursor and Manus —
will discover the OAuth endpoints automatically and walk the user through a
one-time login at Windsor.ai. Dynamic Client Registration is supported.

- Discovery: `https://mcp.windsor.ai/.well-known/oauth-authorization-server`
- Authorization endpoint (proxied): `https://onboard.windsor.ai/oauth/authorize`
- Token endpoint (proxied): `https://onboard.windsor.ai/oauth/token`

### API Key

Pass a Windsor.ai API key as a Bearer token:

```
Authorization: Bearer <your_windsor_api_key>
```

Get an API key from your Windsor.ai account settings: https://onboard.windsor.ai/

## Compatible AI Clients

Windsor.ai MCP works with any MCP-compatible client, including:

- Claude (Anthropic) — listed in the Claude connector directory
- ChatGPT (OpenAI)
- Cursor, Windsurf, Cline, GitHub Copilot
- Google Gemini, Microsoft Copilot
- Manus
- n8n, mcp-proxy, and custom MCP clients

## Workflow

1. `get_connectors()` — list connectors that already have connected accounts.
   Pass `include_not_yet_connected=True` to also see connectors the user has
   not set up yet.
2. If the user wants a connector that is not connected, call
   `get_connector_authorization_url(connector=...)` to get a browser link they
   can open to authorize the connector (works for both OAuth and manual flows).
3. `get_options(connector=..., accounts=[...])` — list available fields, date
   filter columns, and connector-specific options for the chosen account set.
4. `get_fields(connector=..., fields=[...])` — get descriptions, types, and
   tables for the fields you plan to query. Fields with `NUMERIC` or `PERCENT`
   types are metrics; everything else is a dimension.
5. `get_data(connector=..., fields=[...], ...)` — run the query with optional
   date range, accounts, options, and filters.

## Available Tools

### `get_current_user`

Return the authenticated user's profile. Useful as a sanity check that the
auth token is working and to greet the user by name.

Returns: `{ "username": str, "email": str }`

### `get_connectors`

List Windsor.ai connectors and their connected accounts.

Parameters:
- `include_not_yet_connected: bool = False` — if true, also return connectors
  that the user could set up but hasn't connected an account to yet.

Returns: `[{ "id": str, "accounts": [{ "id": str, "name": str | None }] | None }]`

### `get_connector_authorization_url`

Returns a URL the user can open in their browser to set up a connector.
Handles both OAuth-based and manual-credential connectors.

Parameters:
- `connector: str` — connector ID. Always call
  `get_connectors(include_not_yet_connected=True)` first to obtain the correct
  ID.

Returns: a string URL.

### `get_options`

List available fields, date filter columns, and connector-specific options.

Parameters:
- `connector: str` — connector ID, e.g. `"facebook"`, `"google_ads"`,
  `"tiktok"`, `"linkedin"`.
- `accounts: list[str]` — account IDs.

Returns: `{ "fields": [str], "date_filters": { table: [str] }, "options": [...] }`

### `get_fields`

Get detailed descriptions, types and tables for specific fields.

Parameters:
- `connector: str`
- `fields: list[str]` — list of field IDs.

Returns: `[{ "id": str, "name": str, "description": str, "type": str, "table": str | None }]`

Field types: `NUMERIC` and `PERCENT` are metrics (aggregated); everything
else is a dimension (grouped by).

### `get_data`

Retrieve data from a connector. The most powerful tool — supports date
ranges, account filtering, custom field filters, and connector-specific
options.

Parameters:
- `connector: str`
- `fields: list[str]` — field IDs to retrieve.
- `accounts: list[str] | None` — optional list of account IDs to filter by.
- `date_filters: dict[str, str] | None` — override the default date column
  per table (e.g. `{"orders": "created_at"}`).
- `date_from: date | None`
- `date_to: date | None`
- `date_preset: str | None` — e.g. `"last_7d"`, `"last_30d"`, `"last_3m"`,
  `"last_year"`, `"this_month"`, `"this_yearT"` (`T` suffix means including
  today).
- `options: dict | None` — connector-specific options, e.g.
  `{"attribution_window": "7d_view,1d_click"}` for Meta Ads.
- `filters` — nested condition list, e.g.
  `[["spend", "gt", 100], "and", ["campaign", "contains", "Sale"]]`.
  Supported operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`,
  `ncontains`, `null`, `notnull`, `in`.

Returns: a list of records.

Some warehouse connectors (`mysql`, `postgresql`, `redshift`, `mongodb`,
`snowflake`, `big_query`) require `date_filters` when filtering by date.

## Use Case Examples

- "Pull last month's Meta Ads spend by campaign and compare to the previous
  period."
- "Show me Google Ads ROAS by campaign for the last 30 days."
- "List my connected TikTok Ads accounts and pull last week's performance."
- "Combine Meta Ads, Google Ads, and TikTok Ads spend into a unified weekly
  report."
- "Pull Shopify orders and Klaviyo email engagement so I can attribute revenue."
- "Query my BigQuery warehouse for last quarter's pipeline data."
- "Build a Looker Studio-ready dataset combining GA4 sessions and ad spend."

## Supported Data Sources

The full list of 325+ supported connectors is dynamic — call
`get_connectors(include_not_yet_connected=True)` from your MCP client or fetch
`GET https://mcp.windsor.ai/datasources` for the up-to-date list.

Highlights by category:

### Advertising
Meta Ads (Facebook & Instagram), Google Ads, Microsoft Ads (Bing),
TikTok Ads, LinkedIn Ads, Snapchat, Pinterest, Reddit, X/Twitter, Amazon Ads,
Apple Search Ads, Criteo, Taboola, Outbrain, DV360, Campaign Manager 360,
Search Ads 360, AdRoll, AdForm, StackAdapt, The Trade Desk, RTB House,
Quora Ads, MNTN, Basis DSP, MediaGo, Yahoo Japan Ads, Line Ads, Yandex.Direct,
Vibe, Flashtalking, AppNexus.

### Analytics & Search
Google Analytics 4 (GA4), Universal Analytics, Adobe Analytics, Mixpanel,
Amplitude, Matomo, Plausible, PostHog, FullStory, Search Console, Bing
Webmaster, PageSpeed Insights, Looker, Metabase.

### Social (Organic & Public)
Facebook Organic, Instagram, Instagram Public, LinkedIn Organic, TikTok
Organic, Pinterest Organic, X Organic (Twitter), Threads, YouTube,
Sprout Social.

### CRM & Marketing Automation
HubSpot, Salesforce, Salesforce Marketing Cloud, Pipedrive, Microsoft
Dynamics 365, Zoho CRM, Copper, Close.com, Insightly, Monday.com, Pardot,
Mailchimp, Klaviyo, ActiveCampaign, Brevo (Sendinblue), MailerLite,
Mailgun, MailerSend, Mailjet, Omnisend, Customer.io, Iterable,
SendGrid, Drift, Intercom, Outreach, Salesloft, Reply.io, Lemlist.

### E-commerce & Payments
Shopify, Magento, WooCommerce, BigCommerce, PrestaShop, Square, Stripe,
PayPal, Braintree, Klarna, Recharge, Recurly, Chargebee, Chargify, Paystack,
Walmart, TikTok Shop.

### Affiliate & Partner Marketing
CJ, Awin, Impact, Partnerize, PartnerStack, Adtraction, Daisycon,
Commission Factory, Rakuten Advertising, ShareASale, Tradedoubler, Everflow.

### App Analytics & Attribution
AppsFlyer, Adjust, Branch, AppFollow.

### Customer Support & Helpdesk
Zendesk (Support, Chat, Sell, Sunshine, Talk), Freshdesk, Freshcaller,
Freshservice, Dixa, Drift, Intercom.

### Databases, Warehouses & Files
BigQuery, Snowflake, PostgreSQL, MySQL, Redshift, MongoDB, Firebolt,
Dremio, SFTP, Google Sheets, Airtable, Notion, Amazon S3.

### HR, Finance, Productivity, Other
BambooHR, Ashby, Lever, Greenhouse, Recruitee, Workable, QuickBooks, Xero,
NetSuite, Slack, Microsoft Teams, Twilio, Zoom, Jira, Confluence, GitHub,
GitLab, Datadog, Sentry, PagerDuty, and many more.

For the complete authoritative list, fetch `/datasources` or call
`get_connectors(include_not_yet_connected=True)`.

## Troubleshooting

### Authentication failures (401)

- Confirm the Authorization header is `Bearer <token>` (no quotes).
- For API keys: get one from https://onboard.windsor.ai/.
- For OAuth: clear cached tokens in your client and re-authorize.

### Tool errors

- "Requested data exceeds size limit": narrow the date range, reduce fields,
  filter by accounts, or add filters.
- "Connector requires specifying date filters": pass `date_filters` for
  warehouse connectors (mysql, postgresql, redshift, mongodb, snowflake,
  big_query).
- "Not authenticated": no valid token reached the server — check headers.

### Connector not connected

If `get_connectors()` does not list the connector the user wants, call
`get_connector_authorization_url(connector=...)` and have the user open the
returned URL to set up the connector. Then re-run `get_connectors()`.

## Support

- Windsor.ai homepage: https://windsor.ai/
- Onboarding & account: https://onboard.windsor.ai/
- Issues: contact Windsor.ai support