# 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](https://app.adexecai.shop/docs/api.md) · [Machine-readable index](https://app.adexecai.shop/llms.txt)

## 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.

| 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:

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

Get the authorization-server metadata:

```bash
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

```bash
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.

```text
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

```bash
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

```bash
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

```bash
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:

```bash
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:

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

## List tools

```bash
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 |

<!-- MCP_TOOLS_END -->

## Call a tool

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

```bash
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:

```json
{
  "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`:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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.

```json
{
  "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.

## Related documentation

- [REST API documentation](https://app.adexecai.shop/docs/api.md)
- [Human-readable REST API documentation](https://app.adexecai.shop/docs/api)
- [AI-readable documentation index](https://app.adexecai.shop/llms.txt)
