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

# Connect an AI agent to Adclear (MCP)

> Let Claude, ChatGPT, Cursor or your own agent read and manage promotions in Adclear through the Model Context Protocol.

Adclear runs a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. Any MCP client that supports remote servers with OAuth can connect to it: Claude, ChatGPT, Cursor, or an agent you build with an MCP SDK. The agent acts as the person who signed in, with that person's role and permissions, so it can see and do exactly what they can in the Adclear app.

Through the server an agent can check promotion status, read comments from Adclear AI and from reviewers, follow links to items in the app, upload new promotions and new versions, and read dashboard metrics. The tools describe themselves to the agent, so you don't need to configure them one by one.

## Endpoint

| Environment | MCP endpoint |
| - | - |
| Production | `https://mcp.adclear.ai/mcp` |

The server uses the MCP Streamable HTTP transport (JSON-RPC 2.0 over `POST`). It publishes its OAuth details at `https://mcp.adclear.ai/.well-known/oauth-protected-resource/mcp`, which MCP clients read on their own.

## Before you connect

Adclear doesn't support dynamic client registration. Each MCP client needs an OAuth client that Adclear registers for you.

<Steps>
  <Step title="Send Adclear your redirect URIs">
    Tell your Adclear contact which client you'll use and the OAuth redirect URI (callback URL) it signs in with. For command-line and desktop clients that listen on a local port, the loopback address `http://127.0.0.1/callback` covers any port.
  </Step>

  <Step title="Receive your client ID">
    Adclear registers the client and sends you its client ID. There is no client secret: the client is public and uses PKCE.
  </Step>

  <Step title="Add the server to your client">
    Enter the endpoint and the client ID in your MCP client (see the examples below), then sign in with your Adclear account.
  </Step>
</Steps>

## How sign-in works

The server is an OAuth 2.1 protected resource. Adclear's sign-in is the authorization server.

* **Flow:** authorization code with PKCE, using the `S256` challenge method.
* **Resource:** send `resource=https://mcp.adclear.ai/mcp` on both the authorization and the token request. It must match exactly (no trailing slash). Adclear rejects tokens issued for any other resource.
* **Scopes:** `openid profile email offline_access user:org:read`. `user:org:read` is what puts your organisation in the token.
* **Organisation:** you choose the organisation on the consent screen. To work in a different organisation, reconnect and choose it there.
* **Refresh tokens:** `offline_access` returns a refresh token. Long-running agents should refresh the access token when it expires instead of asking the user to sign in again.

If a request is rejected, the `WWW-Authenticate` response header tells the client what to do:

| Status | Header | Meaning |
| - | - | - |
| 401 | `Bearer scope="...", resource_metadata="..."` | No token. Start the sign-in flow. |
| 401 | `error="invalid_token"` | The token is expired, malformed or was issued for another resource. `error_description` says which. |
| 403 | `error="insufficient_scope", scope="user:org:read"` | The token has no organisation. Sign in again and choose an organisation. |

## Examples

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http --client-id <your-client-id> \
      --callback-port 8765 adclear https://mcp.adclear.ai/mcp
    ```

    Then run `/mcp` in Claude Code and choose **adclear** to sign in. Claude Code listens on `http://127.0.0.1:8765/callback`, which the loopback redirect URI covers.
  </Tab>

  <Tab title="Claude, ChatGPT and Cursor">
    Add a custom connector (remote MCP server) with the URL `https://mcp.adclear.ai/mcp`. In the connector's OAuth or advanced settings, enter the client ID Adclear gave you and leave the client secret empty. The client handles the rest of the sign-in.
  </Tab>

  <Tab title="Your own agent">
    Use an MCP SDK client with OAuth support and a pre-registered client. For example, with the TypeScript SDK:

    ```typescript theme={null}
    import { Client } from '@modelcontextprotocol/sdk/client/index.js';
    import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

    const transport = new StreamableHTTPClientTransport(
      new URL('https://mcp.adclear.ai/mcp'),
      // Your OAuthClientProvider: returns the client ID Adclear issued from
      // clientInformation(), stores tokens, and sends the user to sign in.
      { authProvider }
    );
    const client = new Client({ name: 'my-agent', version: '1.0.0' });
    await client.connect(transport);
    const { tools } = await client.listTools();
    ```

    If you handle OAuth yourself, send the access token as `Authorization: Bearer <token>` on every request.
  </Tab>
</Tabs>

## Workspaces

Calls use your organisation's default workspace.

Clients that can send custom headers can choose another workspace on each request with `X-Adclear-Workspace-Id: <workspace id>`. The workspace must belong to the organisation you signed in to, and you must have access to it. Clients that can't send custom headers use the default workspace.

## Rate limits

| Limit | Applies to |
| - | - |
| 120 requests per minute | Each signed-in user. A large dashboard query can count as up to 6 requests. |
| 30 requests per minute | Each IP address, for requests whose token hasn't been used successfully yet, and for failed sign-ins. |
| 1,000 requests per minute | Each IP address, for all traffic. |

Over a limit, the server answers `429` with a `Retry-After` header in seconds. Wait that long before retrying.

## Errors and support

Every response carries an `X-Correlation-ID` header. When a tool fails, its result includes a `correlationId`, and protocol errors carry it in `error.data.correlationId`. Quote it to Adclear support so we can find the request.

A tool that timed out or lost its connection says so, and says whether a retry is safe. Tools that create things accept an `idempotencyKey`: retrying with the same key returns the first result instead of creating a duplicate.

<Note>
  Tokens are tied to the person who signed in. Every change an agent makes is recorded in Adclear's audit history as that person, through MCP.
</Note>

## Choosing a workspace

An organisation can have several workspaces. A call that names no workspace uses the one you chose, otherwise your organisation's default workspace, or, if you can't use the default, the first workspace you can use.

<Steps>
  <Step title="See where you are">
    Ask your agent to call `getMyContext`. It shows who you're signed in as, your organisation and role, what you may do, and the workspace your calls use now.
  </Step>

  <Step title="List your workspaces">
    `listWorkspaces` lists the workspaces you can use, with their ids.
  </Step>

  <Step title="Switch">
    `selectWorkspace` with one of those ids switches to it. The switch applies from your next call, and the choice is kept for later calls, in new conversations too, until you choose another. It is kept per organisation. If you lose access to the chosen workspace, calls go back to the default.
  </Step>
</Steps>

Clients that can send custom headers can instead pin a workspace on each request with `X-Adclear-Workspace-Id: <workspace id>`. The header wins over a stored choice.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.