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
- Register your MCP client using dynamic client registration.
- Open the authorization URL with PKCE
S256. - Approve the agent connection and scopes in the AdExec dashboard.
- Exchange the authorization code for a bearer access token.
- Send
initialize, thentools/list, thentools/callto 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.
| Property | Value |
|---|---|
| Authorization code lifetime | 60 seconds |
| Access token lifetime | 15 minutes |
| Refresh token lifetime | 30 days |
| PKCE method | S256 |
| Token endpoint auth method | none |
| Access token type | Bearer, audience-bound to https://mcp.adexecai.shop |
| Refresh rotation | Single-use refresh tokens; reuse revokes the whole token family |
| Revocation | RFC 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:
| Method | URL | Purpose |
|---|---|---|
POST | https://mcp.adexecai.shop/oauth/register | Dynamic client registration |
GET | https://mcp.adexecai.shop/oauth/authorize | Start authorization and redirect to dashboard consent |
POST | https://mcp.adexecai.shop/oauth/token | Exchange code or refresh token |
POST | https://mcp.adexecai.shop/oauth/revoke | Revoke 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
| Scope | Grants access to |
|---|---|
brands:read | brands.list, brands.get_context |
campaigns:read | campaigns.list |
campaigns:write | campaigns.create |
assets:read | assets.search, assets.get |
assets:write | Asset mutation capability; no current MCP tool requires it |
creative:generate | Image/video generation and generation-status tools |
publishing:request | Drafting, scheduling, publishing status, and channel listing |
approvals:read | Approval-status reads |
usage:read | Credit 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. -->| # | Tool | Description | Required scope | Input schema summary |
|---|---|---|---|---|
| 1 | brands.list | List the brands this connection may access. | brands:read | required: none; no additional properties |
| 2 | brands.get_context | Load a brand kit and its publishing policy. | brands:read | required: brand_id (string); no additional properties |
| 3 | campaigns.list | List campaigns. | campaigns:read | required: none; optional: brand_id (string); no additional properties |
| 4 | campaigns.create | Create a campaign for a brand. | campaigns:write | required: brand_id (string), name (string; maxLength: 200), idempotency_key (string; maxLength: 200); no additional properties |
| 5 | assets.search | Search asset metadata in the caller organization and brand scope. | assets:read | required: none; optional: brand_id (string), campaign_id (string), type (enum: image, video), limit (integer; min: 1; max: 100); no additional properties |
| 6 | assets.get | Get asset metadata and eligibility. | assets:read | required: asset_id (string); no additional properties |
| 7 | creative.generate_image | Request an image from AdExec Image. | creative:generate | required: 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 |
| 8 | creative.agnes_image | Request an image from AdExec Image. | creative:generate | required: 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 |
| 9 | creative.generate_video | Request a video from AdExec Video. | creative:generate | required: 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 |
| 10 | creative.get_generation_status | Check a generation job. | creative:generate | required: job_id (string); no additional properties |
| 11 | publishing.create_draft | Create a publishing draft for a post. | publishing:request | required: 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 |
| 12 | publishing.request_schedule | Request immediate or scheduled publishing. Auto-publish organizations use a system approval; manual organizations wait for a human approver. | publishing:request | required: draft_id (string), idempotency_key (string; maxLength: 200); optional: scheduled_at (string; format: date-time), publish_now (boolean); no additional properties |
| 13 | publishing.get_status | Check the approval and publishing status of a request. | publishing:request | required: approval_id (string); no additional properties |
| 14 | approvals.get_status | Check the status of an approval. | approvals:read | required: approval_id (string); no additional properties |
| 15 | channels.list | List connected social channels. | publishing:request | required: none; optional: brand_id (string); no additional properties |
| 16 | usage.get_balance | Get the workspace credit balance and limits. | usage:read | required: none; no additional properties |
| 17 | usage.get_quote | Quote the credits an operation would consume. | usage:read | required: operation (string); optional: parameters (object{quality, model, size, duration_seconds, ratio, first_frame_asset_id, reference_asset_ids}; no extra keys); no additional properties |
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:
usage.get_quoteto price the operation.creative.generate_image,creative.agnes_image, orcreative.generate_videoto enqueue the job.creative.get_generation_statusto poll.usage.get_balanceto 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:
publishing.create_draftcreates a content draft.publishing.request_schedulerequests immediate or scheduled publishing.publishing.get_statusorapprovals.get_statusreports status.- 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 code | HTTP status | Meaning |
|---|---|---|
-32700 | 400 | Parse error |
-32600 | 400 | Invalid JSON-RPC request |
-32601 | 404 | Unknown method or tool |
-32602 | 400 | Invalid 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. |
-32001 | 401 | Missing or invalid OAuth token |
-32002 | 403 | Policy, scope, connection, workspace, or brand rejection |
-32003 | 429 | Rate limited |
-32603 | 500 | Internal error |
Common customer-safe error codes include:
error.code / data.code | Meaning |
|---|---|
invalid_token | OAuth token is missing, expired, invalid, or for the wrong audience |
insufficient_scope | Connection or role does not grant the required scope |
connection_expired | Agent connection expired |
connection_revoked | Agent connection was revoked |
workspace_pending_approval | Workspace is not approved yet |
workspace_suspended | Workspace is suspended |
not_found | Resource is absent or outside the caller's brand scope |
invalid_argument | JSON-RPC parameters or tool arguments are invalid |
idempotency_conflict | Idempotency key was reused for a different request |
insufficient_credits | Wallet cannot afford the quoted operation |
budget_exceeded | Connection or workspace budget policy rejected the call |
price_unavailable | No capability price is configured; the tool refuses rather than quoting zero |
approval_required | Publishing needs human approval |
approval_expired | Approval window has passed |
approval_invalidated | Approved payload changed and the approval was invalidated |
policy_violation | Publishing policy rejected the request |
channel_required | A social channel must be connected first |
invalid_publish_time | Scheduling arguments are missing, conflicting, or invalid |
invalid_asset | Referenced asset is missing, not ready, or not eligible |
rate_limited | Request rate limit exceeded |
generation_service_error | Generation service failed |
publishing_service_error | Publishing service failed |
internal_error | Unclassified 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.