Skip to main content
This page is for developers who connect their own agent or MCP client to Adclear. To connect Claude, ChatGPT or Cursor, read Connect Adclear to your AI assistant. For the list of tools, read Tools and permissions.
MCP is in closed beta. To get access, contact your Adclear account manager.

​
Endpoint

The server sends instructions at initialize, and each tool describes its own input. MCP SDK clients read both automatically.

​
Authentication

The server is an OAuth 2.1 protected resource. Adclear sign-in is the authorization server. Every token acts as the user who signed in, with that user’s role and permissions.
  • Client: use the client ID that your Adclear account manager gives you. The client is public, so there is no client secret. Adclear does not support dynamic client registration.
  • Flow: authorization code with PKCE.
  • Resource: send resource=https://mcp.adclear.ai/mcp on the authorization request and the token request. Adclear rejects a token issued for a different resource.
  • Scopes: openid profile email offline_access user:org:read. The user:org:read scope puts the organisation in the token.
  • Organisation: the user chooses one organisation on the consent screen. To use a different organisation, the user signs in again.
  • Refresh tokens: offline_access gives a refresh token. Refresh the access token when it expires. Do not ask the user to sign in again.
Send the access token on every request as Authorization: Bearer <token>.

​
Authentication errors

When Adclear rejects a request, the WWW-Authenticate header tells the client what to do.

​
Workspaces

Each request uses one workspace. Adclear chooses it in this order:
  1. The X-Adclear-Workspace-Id request header, if you send it.
  2. The workspace the user chose with selectWorkspace, if the user can still use it.
  3. The organisation’s default workspace, if the user can use it.
  4. The first workspace the user can use, by name.
If the user can use no workspace, the request fails with 403. The workspace in the header must belong to the token’s organisation, and the user must have access to it.

​
Upload a local file

An agent can create a promotion from a public https link with sourceUrls on createPromotion. To upload a local file, use three steps.
1

Declare the file

Call createUpload with the file name, MIME type and exact size in bytes. The result has an uploadId, an uploadUrl on https://files.adclear.ai, the headers to send and a curlExample you can run.
2

Send the bytes

Send the file to uploadUrl with HTTP PUT. Send Content-Type and Content-Range headers. A file of 50 MB or less goes in one request. A larger file goes in the chunks listed in chunks. Each chunk is 50 MB or less, and each chunk except the last is a multiple of 256 KiB. The link works for 2 hours and only for this upload.
3

Complete the upload

Call completeUpload with the uploadId. Adclear checks that the file content matches the declared type. Then pass the uploadId in uploadIds to createPromotion or createPromotionVersion.
If the agent runs in a sandbox with a network allowlist, the allowlist must include files.adclear.ai. The agent never needs access to any other storage domain.

​
Retries and idempotency

createPromotion, createPromotionVersion, submitPromotion and precheckPromotion accept an idempotencyKey. Send a new key for each new action. Send the same key when you retry. A retry with the same key returns the first result and does not create a duplicate. Adclear keeps each key for 24 hours. If a tool times out or loses its connection, the result says that the outcome is unknown and whether a retry is safe.

​
Paging

List tools return hasMore. While hasMore is true, call the tool again with the nextPage or nextOffset value from the result.

​
Rate limits

When a request goes over a limit, the server returns 429 with a Retry-After header in seconds. Wait for that time, then retry.

​
Errors and support

Every response has an X-Correlation-ID header. A failed tool result includes a correlationId. A protocol error has it in error.data.correlationId. Give this ID to Adclear support when you report a problem.