@cesteral/ttd-mcp

@cesteral/ttd-mcp

TTD MCP Server - The Trade Desk campaign entity management and reporting via TTD API v3.

Purpose

Management and reporting server for The Trade Desk. Provides full CRUD operations on TTD campaign entities (advertisers, campaigns, ad groups, ads) and on-demand report generation via the MyReports API. Designed for AI agents to manage TTD campaigns programmatically through the Model Context Protocol.

Features

• Per-session authentication via SessionServiceStore pattern
• Direct API token auth using the TTD-Auth header
• OpenTelemetry instrumentation for traces and metrics
• Rate limiting via shared RateLimiter class
• MCP protocol with Streamable HTTP transport (Hono)
• Structured output with outputSchema on all tools

MCP Tools

Core CRUD

Tool	Description
ttd_list_entities	List TTD entities with optional filtering and pagination
ttd_get_entity	Get a single TTD entity by ID
ttd_create_entity	Create a new TTD entity
ttd_update_entity	Update an existing TTD entity (PUT)
ttd_delete_entity	Delete a TTD entity by ID
ttd_validate_entity	Dry-run validate entity payload without persisting

Reporting

ttd_download_report accepts the shared bounded report-view params: mode ("summary" default — headers + counts + 10-row preview, or "rows" for a paginated rows page), columns (project to selected columns), offset (zero-based pagination), and maxRows (page size; default 10 for summary, 50 for rows; hard cap 200).

Tool	Description
ttd_get_report	Generate async report via MyReports V3 API
ttd_download_report	Download report CSV and return a bounded view
ttd_submit_report	Submit report without waiting (non-blocking)
ttd_check_report_status	Single status check for a submitted report

Bulk Operations

Tool	Description
ttd_bulk_create_entities	Batch create campaigns/ad groups (up to 50)
ttd_bulk_update_entities	Batch update campaigns/ad groups (up to 50)
ttd_bulk_update_status	Batch pause/resume/archive entities
ttd_archive_entities	Batch archive (soft-delete) entities
ttd_adjust_bids	Batch adjust ad group bid CPMs (safe read-modify-write)
ttd_bulk_manage_bid_lists	Batch get/update bid lists (up to 50)

Bid Lists

Tool	Description
ttd_manage_bid_list	Create, get, or update a single bid list (create/get/update)

Audience / Seeds

Tool	Description
ttd_manage_seed	Manage audience seeds via GraphQL (create, update, get, set_default_advertiser, attach_to_campaign)

Advanced (GraphQL)

Tool	Description
ttd_graphql_query	Execute GraphQL query/mutation against TTD GraphQL API
ttd_graphql_query_bulk	Execute bulk GraphQL queries
ttd_graphql_mutation_bulk	Execute bulk GraphQL mutations
ttd_graphql_bulk_job	Submit a GraphQL bulk job
ttd_graphql_cancel_bulk_job	Cancel a running GraphQL bulk job

MyReports Templates and Schedules

Tool	Description
ttd_create_report_template	Create a MyReports template via GraphQL
ttd_update_report_template	Replace an existing MyReports template via GraphQL
ttd_get_report_template	Retrieve template structure, including result-set column IDs
ttd_list_report_templates	List template headers via GraphQL cursor pagination
ttd_create_template_schedule	Create a one-time or recurring template schedule via GraphQL
ttd_update_report_schedule	Enable or disable an existing report schedule via GraphQL
ttd_cancel_report_execution	Cancel an in-progress report execution via GraphQL
ttd_rerun_report_schedule	Trigger a fresh execution from an existing schedule
ttd_get_report_executions	Retrieve execution history, statuses, and download links
ttd_create_report_schedule	Legacy-compatible REST wrapper for schedule creation
ttd_list_report_schedules	List existing report schedules
ttd_get_report_schedule	Get a specific report schedule
ttd_delete_report_schedule	Delete a report schedule

Preview

Tool	Description
ttd_get_ad_preview	Get preview URL and metadata for a TTD creative

GraphQL API Reference

TTD exposes a GraphQL API alongside its REST API. All GraphQL calls go to:

POST https://desk.thetradedesk.com/graphql
TTD-Auth: <api_token>
Content-Type: application/json

Introspection is disabled. __type queries return null. The full query reference is available as an MCP resource at graphql-reference://ttd — call resources/read on that URI for working patterns and known field constraints.

Authentication

Same TTD-Auth token as the REST API. Set via session headers (HTTP mode) or TTD_API_TOKEN env var (stdio mode).

Cold Start

{
  partners {
    nodes {
      id
      name
    }
  }
}

Returns all accessible partner IDs. Use with ttd_list_entities (entityType: "advertiser") or the ttd_get_context tool.

Pagination

TTD uses two styles depending on the endpoint:

Style	Used for
edges { node { ... } } pageInfo { hasNextPage endCursor }	campaigns, adGroups, and most entity queries
nodes { ... } pageInfo { hasNextPage endCursor }	partners, report templates

Add first: N and after: "cursor" for forward pagination.

Mutation Pattern

All mutations return data + errors (or userErrors on entity report mutations):

mutation ExampleMutation($input: ExampleInput!) {
  exampleMutation(input: $input) {
    data {
      id
    }
    errors {
      __typename
      ... on MutationError {
        field
        message
      }
    }
  }
}

Enum values are UPPERCASE in JSON variables ("format": "EXCEL", "dateFormat": "INTERNATIONAL").

Seed / Audience Management

Operation	Mutation / Query
Create seed	seedCreate(input: { advertiserId, name, ... })
Update seed	seedUpdate(input: { id, ... })
Get seed	query { seed(id: $id) { id name status quality activeSeedIdCount } }
Set advertiser default seed	advertiserSetDefaultSeed(input: { advertiserId, seedId })
Attach seed to campaign	campaignUpdateSeed(input: { campaignId, seedId })

Use ttd_manage_seed to execute these without writing GraphQL manually.

Bulk GraphQL Jobs

Run the same query or mutation across many variable sets in parallel:

mutation CreateQueryBulk($input: CreateQueryBulkInput!) {
  createQueryBulk(input: $input) {
    data {
      id
      status
    }
    errors {
      __typename
    }
  }
}

Variables: { "input": { "query": "...", "queryVariables": "[{...},{...}]" } } (variables JSON-encoded as a string).

Poll with { bulkJob(id: $id) { status url } } — results expire after 1 hour. Use ttd_graphql_query_bulk, ttd_graphql_mutation_bulk, ttd_graphql_bulk_job, and ttd_graphql_cancel_bulk_job to avoid managing this flow manually.

Error Codes

All GraphQL errors return HTTP 200. Check errors[].extensions.code:

Code	Meaning
AUTHENTICATION_FAILURE	Invalid or expired token
VALIDATION_FAILURE	Input failed server-side validation
GRAPHQL_VALIDATION_FAILED	Query syntax / field error
RESOURCE_LIMIT_EXCEEDED	Rate or complexity limit hit — reduce page size or retry
NOT_FOUND	Entity does not exist
UNAUTHORIZED_FIELD_OR_TYPE	Feature not enabled on account (e.g. MyReports)

Supported Entity Types

Entity Type	API Path	ID Field
advertiser	/advertiser	AdvertiserId
campaign	/campaign	CampaignId
adGroup	/adgroup	AdGroupId
ad	/ad	AdId
creative	/creative	CreativeId
siteList	/sitelist	SiteListId
deal	/deal	DealId
conversionTracker	/tracking/conversion	TrackingTagId
bidList	/bidlist	BidListId

Entity Hierarchy: partner > advertiser > campaign > adGroup > ad

Current Status

Phase: Production-Ready

All listed tools are implemented using TTD API v3 and GraphQL. Entity CRUD, bulk operations, GraphQL passthrough, MyReports templates/schedules, and creative preview are available via TTD API token authentication.

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm run dev:http

# Build
pnpm run build

# Start production server
pnpm run start

# Type check
pnpm run typecheck

# Lint
pnpm run lint

Environment Variables

• TTD_MCP_PORT: Server port (default: 3003)
• TTD_API_TOKEN: Preferred direct TTD API token for stdio mode or env-based HTTP sessions
• MCP_AUTH_MODE: Authentication mode - ttd-token (default), jwt, or none
• MCP_AUTH_SECRET_KEY: Required when MCP_AUTH_MODE=jwt

Architecture

Key Components

• TtdHttpClient - HTTP client for TTD API v3, accepts TtdAuthAdapter
• TtdEntityService - CRUD operations for all supported entity types
• TtdReportingService - Report generation via MyReports API
• TtdTokenAuthStrategy - Reads direct API tokens from the TTD-Auth header
• SessionServiceStore - Per-session service instances keyed by session ID

Key Gotchas

• TTD uses PUT for updates (full entity replacement, not PATCH)
• AdvertiserId is required in most entity payloads
• Report generation is async: submit → poll → download CSV
• MyReports templates and schedules are separate concepts; GraphQL is the primary path for template-driven reporting
• Archive is a soft-delete; archived entities cannot be reactivated
• Direct TTD-Auth API tokens can be used for both REST and GraphQL requests

Transport

• Streamable HTTP: MCP protocol via Hono + @hono/mcp
• Health check: /health endpoint

Contributing

See root CLAUDE.md for development guidelines, build system details, and monorepo conventions. See the root README for full architecture context.

Get Started

Self-host: Follow the deployment guide to run this server on your own infrastructure.

Cesteral Intelligence: Request access -- governed execution with credential brokering, approvals, audit, and multi-tenant access.

Book a workflow demo: See it in action with your own ad accounts.

Compare options: OSS connectors vs Cesteral Intelligence

License

Apache License 2.0 — see LICENSE for details. This package is part of Cesteral's open-source connector layer; managed hosting and higher-level governance features live outside this repository.