Canonical MarkdownView Markdown

AdExec MCP

This Markdown file is the machine-readable source for the HTML page at https://app.adexecai.shop/docs/mcp. The page renders this exact file. Tool rows are generated from workers/mcp/src/mcp/tools.ts.

Canonical endpoint: https://mcp.adexecai.shop/mcp

Transport: Streamable HTTP using JSON-RPC 2.0 over POST.

Server identity: adexec-mcp version 1.0.0.

Related: REST API documentation ยท Machine-readable index

Quick start

  1. Register your MCP client using dynamic client registration.
  2. Open the authorization URL with PKCE S256.
  3. Approve the agent connection and scopes in the AdExec dashboard.
  4. Exchange the authorization code for a bearer access token.
  5. Send initialize, then tools/list, then tools/call to the MCP endpoint.

Every MCP request, including initialize and tools/list, requires a valid OAuth access token. An unauthenticated request receives HTTP 401 with invalid_token and a resource-metadata pointer.

OAuth 2.1

AdExec implements OAuth 2.1 authorization-code flow with PKCE. Public clients are supported and do not need a client secret.

PropertyValue
Authorization code lifetime60 seconds
Access token lifetime15 minutes
Refresh token lifetime30 days
PKCE methodS256
Token endpoint auth methodnone
Access token typeBearer, audience-bound to https://mcp.adexecai.shop
Refresh rotationSingle-use refresh tokens; reuse revokes the whole token family
RevocationRFC 7009 endpoint; revocation applies to the token family

Discovery

Get the protected-resource metadata:

curl -sS https://mcp.adexecai.shop/.well-known/oauth-protected-resource

Get the authorization-server metadata:

curl -sS https://mcp.adexecai.shop/.well-known/oauth-authorization-server

The published OAuth endpoints are:

MethodURLPurpose
POSThttps://mcp.adexecai.shop/oauth/registerDynamic client registration
GEThttps://mcp.adexecai.shop/oauth/authorizeStart authorization and redirect to dashboard consent
POSThttps://mcp.adexecai.shop/oauth/tokenExchange code or refresh token
POSThttps://mcp.adexecai.shop/oauth/revokeRevoke a refresh-token family

Register a public client

curl -sS https://mcp.adexecai.shop/oauth/register \
  -H 'Content-Type: application/json' \
  --data '{
    "client_name": "My MCP client",
    "redirect_uris": ["http://127.0.0.1:3000/callback"]
  }'

The response includes a client_id. Redirect URIs must match exactly. HTTPS is required except for loopback HTTP redirects used by native clients.

Authorize

Open an authorization URL with a generated PKCE verifier/challenge. Replace the placeholders; do not publish a real verifier.

https://mcp.adexecai.shop/oauth/authorize?
response_type=code&
client_id=$MCP_CLIENT_ID&
redirect_uri=$MCP_REDIRECT_URI&
code_challenge=$PKCE_S256_CHALLENGE&
code_challenge_method=S256&
scope=brands%3Aread%20creative%3Agenerate&
state=$RANDOM_STATE

The AdExec dashboard performs consent and redirects back to the registered redirect URI with code and state.

Exchange the authorization code

curl -sS https://mcp.adexecai.shop/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode "client_id=$MCP_CLIENT_ID" \
  --data-urlencode "code=$AUTH_CODE" \
  --data-urlencode "redirect_uri=$MCP_REDIRECT_URI" \
  --data-urlencode "code_verifier=$PKCE_VERIFIER"

The token response contains access_token, token_type, expires_in, refresh_token, and scope.

Refresh

curl -sS https://mcp.adexecai.shop/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode "client_id=$MCP_CLIENT_ID" \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"

Use the newly returned refresh token on the next refresh. Reusing an already redeemed refresh token revokes the entire token family.

Revoke

curl -sS https://mcp.adexecai.shop/oauth/revoke \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "token=$REFRESH_TOKEN" \
  --data-urlencode "client_id=$MCP_CLIENT_ID"

Scopes

ScopeGrants access to
brands:readbrands.list, brands.get_context
campaigns:readcampaigns.list
campaigns:writecampaigns.create
assets:readassets.search, assets.get
assets:writeAsset mutation capability; no current MCP tool requires it
creative:generateImage/video generation and generation-status tools
publishing:requestDrafting, scheduling, publishing status, and channel listing
approvals:readApproval-status reads
usage:readCredit balance and quote tools

Granted scopes are intersected with the live agent connection and the member role ceiling. A token can only narrow access; it cannot add a scope the connection does not hold.

Initialize

Send JSON-RPC 2.0 over HTTP with the OAuth access token:

curl -sS https://mcp.adexecai.shop/mcp \
  -H "Authorization: Bearer $ADEXEC_MCP_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "docs-example", "version": "1.0.0"}
    }
  }'

Supported protocol versions are 2024-11-05 and 2025-03-26. An unknown requested version falls back to 2024-11-05.

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "serverInfo": {"name": "adexec-mcp", "version": "1.0.0"},
    "capabilities": {"tools": {"listChanged": false}}
  }
}

List tools

curl -sS https://mcp.adexecai.shop/mcp \
  -H "Authorization: Bearer $ADEXEC_MCP_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

tools/list returns every tool name, description, and input schema. The catalogue has exactly 17 tools. Tool arguments never contain tenant or identity fields; organization, member, and connection identity come from the verified token and live database context.

Tools

<!-- MCP_TOOLS_START --> <!-- Generated from workers/mcp/src/mcp/tools.ts. Tool count: 17. -->
#ToolDescriptionRequired scopeInput schema summary
1brands.listList the brands this connection may access.brands:readrequired: none; no additional properties
2brands.get_contextLoad a brand kit and its publishing policy.brands:readrequired: brand_id (string); no additional properties
3campaigns.listList campaigns.campaigns:readrequired: none; optional: brand_id (string); no additional properties
4campaigns.createCreate a campaign for a brand.campaigns:writerequired: brand_id (string), name (string; maxLength: 200), idempotency_key (string; maxLength: 200); no additional properties
5assets.searchSearch asset metadata in the caller organization and brand scope.assets:readrequired: none; optional: brand_id (string), campaign_id (string), type (enum: image, video), limit (integer; min: 1; max: 100); no additional properties
6assets.getGet asset metadata and eligibility.assets:readrequired: asset_id (string); no additional properties
7creative.generate_imageRequest an image from AdExec Image.creative:generaterequired: brand_id (string), prompt (string; maxLength: 4000), idempotency_key (string; maxLength: 200); optional: campaign_id (string), size (enum: 2k, 3k, 4k), reference_asset_ids (array<string>; maxItems: 14; unique); no additional properties
8creative.agnes_imageRequest an image from AdExec Image.creative:generaterequired: brand_id (string), prompt (string; maxLength: 4000), idempotency_key (string; maxLength: 200); optional: campaign_id (string), model (enum: 2.5, 2.1; default: "2.5"), size (enum: 1k, 2k, 3k, 4k; default: "2k"), ratio (enum: 1:1, 3:4, 4:3, 16:9, 9:16, 2:3, 3:2, 21:9; default: "1:1"), reference_asset_ids (array<string>; maxItems: 4); no additional properties
9creative.generate_videoRequest a video from AdExec Video.creative:generaterequired: brand_id (string), prompt (string; maxLength: 4000), idempotency_key (string; maxLength: 200); optional: campaign_id (string), duration_seconds (integer; min: 4; max: 15), ratio (enum: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, adaptive), quality (enum: standard, premium; default: "standard"), first_frame_asset_id (string; format: uuid); no additional properties
10creative.get_generation_statusCheck a generation job.creative:generaterequired: job_id (string); no additional properties
11publishing.create_draftCreate a publishing draft for a post.publishing:requestrequired: brand_id (string), platform (string), body (string; maxLength: 20000), idempotency_key (string; maxLength: 200); optional: campaign_id (string), channel_id (string), title (string; maxLength: 500), asset_ids (array<string>; maxItems: 20; unique); no additional properties
12publishing.request_scheduleRequest immediate or scheduled publishing. Auto-publish organizations use a system approval; manual organizations wait for a human approver.publishing:requestrequired: draft_id (string), idempotency_key (string; maxLength: 200); optional: scheduled_at (string; format: date-time), publish_now (boolean); no additional properties
13publishing.get_statusCheck the approval and publishing status of a request.publishing:requestrequired: approval_id (string); no additional properties
14approvals.get_statusCheck the status of an approval.approvals:readrequired: approval_id (string); no additional properties
15channels.listList connected social channels.publishing:requestrequired: none; optional: brand_id (string); no additional properties
16usage.get_balanceGet the workspace credit balance and limits.usage:readrequired: none; no additional properties
17usage.get_quoteQuote the credits an operation would consume.usage:readrequired: operation (string); optional: parameters (object{quality, model, size, duration_seconds, ratio, first_frame_asset_id, reference_asset_ids}; no extra keys); no additional properties
<!-- MCP_TOOLS_END -->

Call a tool

Tool calls use the tools/call JSON-RPC method. The example below quotes a premium video generation:

curl -sS https://mcp.adexecai.shop/mcp \
  -H "Authorization: Bearer $ADEXEC_MCP_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "usage.get_quote",
      "arguments": {
        "operation": "creative.generate_video",
        "parameters": {"quality": "premium"}
      }
    }
  }'

Mutating generation, campaign, and publishing tools require a client-generated idempotency_key. Repeating the same canonical request returns the original result; reusing a key for a different request returns idempotency_conflict.

Do not send organization_id, tenant_id, member_id, agent_connection_id, provider credentials, or provider workspace identifiers as tool arguments. Runtime validation rejects unknown fields and identity fields.

Generation jobs

Generation tools are durable and return a job handle instead of waiting for media work:

{
  "job_id": "11111111-1111-4111-8111-111111111111",
  "capability": "image",
  "status": "queued",
  "credits_quoted": "10",
  "correlation_id": "corr_01JEXAMPLE"
}

Poll the job with creative.get_generation_status:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "creative.get_generation_status",
    "arguments": {"job_id": "11111111-1111-4111-8111-111111111111"}
  }
}

Job statuses are queued, running, waiting_provider, waiting_approval, succeeded, failed, cancelled, and expired.

A status response includes a safe failure reason whenever one was recorded:

{
  "job_id": "11111111-1111-4111-8111-111111111111",
  "job_type": "creative.generate_video",
  "status": "failed",
  "error_code": "budget_exceeded",
  "error": {
    "code": "budget_exceeded",
    "message": "This request exceeds the workspace budget.",
    "retryable": false
  },
  "created_at": "2026-11-18T11:00:00.000Z",
  "updated_at": "2026-11-18T11:00:10.000Z",
  "correlation_id": "corr_01JEXAMPLE"
}

error is null for a job with no recorded failure. Its code is stable and allowlisted, its message is a fixed sentence derived from that code, and retryable says whether repeating the same request after a short wait is reasonable. Stored provider text is never returned.

The flow is:

  1. usage.get_quote to price the operation.
  2. creative.generate_image, creative.agnes_image, or creative.generate_video to enqueue the job.
  3. creative.get_generation_status to poll.
  4. usage.get_balance to inspect available and reserved credits.

usage.get_quote supports creative.generate_image, creative.agnes_image, creative.generate_video, and publishing.request_schedule. Video pricing uses parameters.quality with standard or premium.

Publishing and approvals

Publishing uses a governed flow:

  1. publishing.create_draft creates a content draft.
  2. publishing.request_schedule requests immediate or scheduled publishing.
  3. publishing.get_status or approvals.get_status reports status.
  4. Manual workspaces wait for a human approver; auto-publish workspaces use a system approval.

publishing.request_schedule requires exactly one of publish_now: true or a valid scheduled_at timestamp. Supplying both or neither returns invalid_publish_time.

publishing.get_status and approvals.get_status report the job's status together with a safe failure reason:

{
  "approval_id": "22222222-2222-4222-8222-222222222222",
  "status": "approved",
  "job_id": "11111111-1111-4111-8111-111111111111",
  "job_status": "failed",
  "error": {
    "code": "publishing_account_not_configured",
    "message": "Publishing is not configured for this workspace. Contact support.",
    "retryable": false
  },
  "correlation_id": "corr_01JEXAMPLE"
}

error is null when the job has not failed. The message is derived from the persisted, allowlisted code; stored provider text is never returned.

Errors

MCP errors use JSON-RPC error objects. The HTTP status is also set appropriately.

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32002,
    "message": "insufficient_scope",
    "data": {
      "code": "insufficient_scope",
      "retryable": false,
      "correlation_id": "corr_01JEXAMPLE"
    }
  }
}
JSON-RPC codeHTTP statusMeaning
-32700400Parse error
-32600400Invalid JSON-RPC request
-32601404Unknown method or tool
-32602400Invalid parameters or tool arguments. A rejected argument (for example first_frame_asset_id that is not an owned, ready asset) is a correctable request, not a server failure.
-32001401Missing or invalid OAuth token
-32002403Policy, scope, connection, workspace, or brand rejection
-32003429Rate limited
-32603500Internal error

Common customer-safe error codes include:

error.code / data.codeMeaning
invalid_tokenOAuth token is missing, expired, invalid, or for the wrong audience
insufficient_scopeConnection or role does not grant the required scope
connection_expiredAgent connection expired
connection_revokedAgent connection was revoked
workspace_pending_approvalWorkspace is not approved yet
workspace_suspendedWorkspace is suspended
not_foundResource is absent or outside the caller's brand scope
invalid_argumentJSON-RPC parameters or tool arguments are invalid
idempotency_conflictIdempotency key was reused for a different request
insufficient_creditsWallet cannot afford the quoted operation
budget_exceededConnection or workspace budget policy rejected the call
price_unavailableNo capability price is configured; the tool refuses rather than quoting zero
approval_requiredPublishing needs human approval
approval_expiredApproval window has passed
approval_invalidatedApproved payload changed and the approval was invalidated
policy_violationPublishing policy rejected the request
channel_requiredA social channel must be connected first
invalid_publish_timeScheduling arguments are missing, conflicting, or invalid
invalid_assetReferenced asset is missing, not ready, or not eligible
rate_limitedRequest rate limit exceeded
generation_service_errorGeneration service failed
publishing_service_errorPublishing service failed
internal_errorUnclassified server failure

Security notes

  • Treat ADEXEC_MCP_ACCESS_TOKEN, REFRESH_TOKEN, PKCE_VERIFIER, upload_url, and presigned upload headers as secrets.
  • Never put credentials in tool arguments or URLs.
  • MCP access tokens are audience-bound; dashboard session cookies and organization API keys are rejected by the MCP endpoint.
  • Revocation and brand/member/workspace checks are evaluated on every call, including tools/list.
  • The MCP gateway returns the frozen public tool names and safe error codes; it does not expose provider credentials or internal provider references.