Connect an AI agent to Adclear (MCP)

Adclear runs a Model Context Protocol (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.

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.

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.

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.

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

Claude Code
Claude, ChatGPT and Cursor
Your own agent

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.

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.

Use an MCP SDK client with OAuth support and a pre-registered client. For example, with the TypeScript SDK:

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.

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.

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.

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.

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.

List your workspaces

listWorkspaces lists the workspaces you can use, with their ids.

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.

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.

Get started

Fundamentals

Adclear API

File API

Connect an AI agent to Adclear (MCP)

Endpoint

Before you connect

Examples

Workspaces

Rate limits

Errors and support

Choosing a workspace

​Endpoint

​Before you connect

​How sign-in works

​Examples

​Workspaces

​Rate limits

​Errors and support

​Choosing a workspace

Endpoint

Before you connect

How sign-in works

Examples

Workspaces

Rate limits

Errors and support

Choosing a workspace