@focusgts/aep-mcp-server

Adobe's MCP lets your agent read Experience Platform. This one lets it work.

46 tools across 12 categories with full read AND write operations — batch ingestion, schema composition, audience activation, data lifecycle, privacy jobs, and datastreams. Self-hosted, Apache 2.0, no invitation required.

Why this exists

Adobe now ships first-party Experience Platform tools through CX Coworker Gateway, its unified MCP endpoint for Adobe CX Enterprise. (Adobe does not brand any part of it "the AEP MCP" — the gateway is one endpoint that surfaces a tool set per product.) It is a genuinely good product, and if all you need is to ask questions about your Experience Platform instance, you should use it.

But its Experience Platform tool set is 8 tools, all read-only — the names are literally search_* — covering schemas, datasets, governance, Query Service, and audit discovery. It does not touch profiles, identity resolution, privacy requests, datastreams, or ingestion. Access is invitation-only, gated behind Adobe organization enablement, and the whole surface is still Beta.

Audiences and destinations do appear, but in a separate Real-Time CDP tool set on the same gateway — and Adobe is explicit that creating, activating, updating, or deleting audiences, destinations, and dataflows is not supported there either. The read-only boundary holds across the whole gateway.

This server covers the other half: the write path, plus the surfaces Adobe's gateway skips entirely. Ingest a batch. Compose a schema from field groups. Create a destination connection and activate an audience to it. Submit a GDPR erasure. Route Edge Network events. Then run it in your own VPC, under Apache 2.0, with nothing to request from your account rep.

The two are complementary, not competing: pair Adobe's gateway for governed reads with this server for the write path.

This server is built to production standards: OAuth Server-to-Server auth with a deduped token cache, structured pino logging with PII redaction, exponential-backoff retries, automatic 401 re-auth, working pagination, structured AEP_{status} error codes, and a graceful-shutdown lifecycle. It runs as a local stdio process that any MCP-compliant client can drive.

Comparison vs Adobe's first-party Experience Platform tools

Adobe's figures were read from their Experience Platform tools page (last updated 17 July 2026): search_datasets, search_class_relations, search_data_access, search_data_lake, search_dule, search_query_service, search_audit, search_allowed_ip_ranges. It is a Beta surface and will change — check their docs for the current figure. The read/write split is the durable difference, not the count.

Tool inventory

46 tools across 12 categories. All prefixed aep_ with verb_noun naming. Tools marked 🔒 change state; 🔥 are destructive. Most destructive tools require an explicit confirmation phrase — see Safety model for exactly which, and for the two deliberate exceptions.

Workflows these unlock

Ingest data end to end create_schema (with field groups) → create_dataset → create_batch → upload_batch_file → complete_batch → get_batch_status

Build and activate an audience create_segment → estimate_segment_size → list_destinations → create_destination_connection → activate_segment

Honour an erasure request get_profile_by_identity → create_record_delete → get_work_order_status

Safety model

Write modes

AEP_MODE sets how much this server may mutate. Reads are never restricted in any mode.

AEP_MODE=read-only     # browse only
AEP_MODE=safe          # default — dev sandboxes are writable
AEP_MODE=production    # writes anywhere; logs a warning at startup

production is a supported posture, not a jailbreak. Plenty of teams have review, staging, and rollback already handled and don't need another layer telling them no. Set it and the guard steps out of the way — the per-tool confirmation gates below still apply, because those are about irreversibility rather than environment.

How safe decides

• On Adobe's classification, never the sandbox name. A production sandbox can be called anything; a sandbox called prod might not be production. Only Adobe's type field from the Sandbox Management API decides.
• Fails closed. If the type can't be determined — the credential can't read sandbox metadata, the API errors, startup hasn't finished — writes are blocked. A credential must not earn write access by being less capable.
• An unrecognised AEP_MODE falls back to safe, so a typo can never grant production writes.

The guard is enforced in the HTTP client rather than per tool, so all 46 tools inherit it and none can forget it. Blocked calls never reach Adobe; they return a structured WRITE_BLOCKED error naming the sandbox, its type, and the fix.

Startup always states the active posture:

SAFE MODE — sandbox is a development sandbox, so writes are ENABLED.
SAFE MODE — sandbox is PRODUCTION, so writes are BLOCKED. Reads work normally.
SAFE MODE — sandbox type could not be confirmed, so writes are BLOCKED (fail-closed).
READ-ONLY MODE — no write, update, or delete will be performed in any sandbox.
PRODUCTION MODE — writes permitted against ANY sandbox, including production.

AEP_ALLOW_PRODUCTION_WRITES=true is deprecated but still honoured as an alias for AEP_MODE=production. If both are set, AEP_MODE wins.

Tool annotations (client-side human-in-the-loop)

Every tool ships MCP annotations — readOnlyHint, destructiveHint, idempotentHint, openWorldHint — derived from the same metadata that builds its description, so the two cannot drift.

These are hints for the client, not enforcement; the guards above do the enforcing. Their value is that an MCP client such as Claude Desktop uses destructiveHint to decide when to interrupt and ask the human before running a call. Without them every tool looks identical to the client and aep_delete_profile gets the same treatment as aep_list_schemas.

A test asserts that destructive list exactly, so adding a fifth destructive tool is a deliberate act rather than an oversight.

Per-tool confirmation gates

Writes are not uniformly gated — uniform gating makes an agent useless. Gates sit where an action is irreversible and wide-reaching:

In every gated case the confirmation is checked before any network call, so a rejected call never reaches Adobe. Rejections are logged at warn.

Dataset expiration is the one gate with a bypass: passing dryRun: true asks Adobe to validate the request and report what would happen without scheduling anything, so there is nothing to confirm. Any call that actually schedules deletion still requires the phrase.

Datastream deletion is ungated on purpose: a datastream is configuration rather than data, recreating one is the same POST body that created it, and gating it would break the programmatic-cleanup use case the tool exists for.

Batch creation and file upload are ungated too. Those writes are additive and recoverable — an unwanted batch can be left uncompleted, and data that did land can be removed with the Data Hygiene tools.

Every tool validates inputs with Zod at the boundary and returns structured errors rather than throwing. aep_upload_batch_file additionally rejects relative paths, non-regular files, path-traversal file names, and oversized payloads before any network call is made.

Architecture

v0.2.0 added Privacy Service for GDPR/CCPA workflows. v0.3.0 added Datastreams for Edge Network event routing. v0.4.0 adds Batch Ingestion and Data Hygiene — the write surfaces Adobe's read-only first-party MCP does not reach — and fixes the pagination and sandbox-scoping defects described in the changelog.

┌─────────────────────────────────────────────────────────┐
│                  MCP Client (any)                        │
│      Claude · Cursor · ChatGPT · Copilot                │
└──────────────────────┬──────────────────────────────────┘
                       │ stdio (JSON-RPC 2.0)
┌──────────────────────┴──────────────────────────────────┐
│              @focusgts/aep-mcp-server                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │ Schemas  │  │ Datasets │  │Identities│  │Profiles│ │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘ │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │ Segments │  │ Sources  │  │  Dests   │  │ Query  │ │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘ │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │ Privacy  │  │Datastream│  │Ingestion │  │Hygiene │ │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘ │
├─────────────────────────────────────────────────────────┤
│  Auth: OAuth 2.0 Server-to-Server (Adobe IMS)          │
│  Token cache · retry · 401 re-auth · pino redact       │
└──────────────────────┬──────────────────────────────────┘
                       │ HTTPS + Bearer + x-sandbox-name
┌──────────────────────┴──────────────────────────────────┐
│        Adobe Experience Platform APIs (live)             │
│  /data/foundation/schemaregistry · /data/core/ups/...   │
└─────────────────────────────────────────────────────────┘

Quickstart

Option A: From npm

npm install -g @focusgts/aep-mcp-server

Option B: From source

git clone https://github.com/focusgts/aep-mcp-server.git
cd aep-mcp-server
npm install
npm run build

Then for both options:

# Get Adobe credentials at developer.adobe.com/console
# Create project → add "Experience Platform API" → OAuth Server-to-Server

cat > .env <<EOF
AEP_CLIENT_ID=your-client-id
AEP_CLIENT_SECRET=your-client-secret
AEP_ORG_ID=your-ims-org-id@AdobeOrg
AEP_SANDBOX_NAME=prod
EOF

# Run the server (Option A)
aep-mcp

# Or run from source (Option B)
npm run dev

The server speaks MCP over stdio. Any MCP-compliant client can drive it.

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "aep": {
      "command": "npx",
      "args": ["-y", "@focusgts/aep-mcp-server"],
      "env": {
        "AEP_CLIENT_ID": "...",
        "AEP_CLIENT_SECRET": "...",
        "AEP_ORG_ID": "...@AdobeOrg",
        "AEP_SANDBOX_NAME": "prod"
      }
    }
  }
}

Cursor / Copilot / ChatGPT Desktop

Any MCP-compliant client works the same way — point its MCP config at npx -y @focusgts/aep-mcp-server with the four env vars above.

Environment Variables

Sandbox scoping. Every tool sends x-sandbox-name, and Query Service derives its database name as <AEP_SANDBOX_NAME>:all. Prior to v0.4.0 the Query Service database was hardcoded to prod:all regardless of this setting — see the changelog.

Entitlement matrix

Not every Adobe org has every AEP product entitlement. Map tools to what your IMS org actually licenses:

If a tool returns AEP_403 it usually means the entitlement is missing rather than a credential problem.

Development

npm install
npm run build        # tsc → dist/
npm run dev          # tsx src/server.ts (hot-reload)
npm test             # vitest (57 tests)
npm run typecheck    # tsc --noEmit
npm run clean        # rm -rf dist

The TypeScript config is strict mode end-to-end. All tool inputs are validated with Zod at the boundary. All logs go to stderr (pino destination 2) — stdout is reserved for the MCP JSON-RPC stream.

Live integration testing

npm run test:live runs a smoke suite against a real Adobe IMS org and AEP sandbox. It exercises the read paths across the schema registry, catalog, identity, profile, segment, source, destination, query, and privacy endpoint families to verify credentials, entitlements, and sandbox scoping end to end.

It is a connectivity and entitlement check rather than full per-tool coverage — the newer Ingestion and Data Hygiene categories are not yet included, and no destructive tool is invoked.

Requires a .env with valid credentials and AEP_SANDBOX_NAME pointing at a non-production sandbox.

Contributing & License

Apache 2.0. See LICENSE and NOTICE.

Built by Focus GTS, an Adobe Silver Solution Partner. Independently developed — not affiliated with or endorsed by Adobe Inc. or Anthropic, PBC.

Bug reports, feature requests, and pull requests are welcome. Open an issue at github.com/Focus-GTS/aep-mcp-server/issues or email dfox@focusgts.com.

About Focus GTS

Focus GTS is an Adobe Silver Solution Partner specializing in Adobe Experience Cloud talent and tooling. We build production-grade developer tools for AEP, AJO, CJA, and Real-Time CDP customers who need more than what ships in the box.

Learn more at https://focusgts.com.