Bid Manager MCP Server

Cesteral MCP Servers

Self-hostable MCP connectors for major advertising platforms.

Use this repo when you want transparent platform integrations, local experimentation, and infrastructure you control. Use Cesteral Intelligence when your team needs approvals before spend commits, credential brokering, auditability, and cross-platform execution from one governed environment.

Try Meta Ads MCP locally (~10 min) | Compare OSS vs Cesteral Intelligence | Book a workflow demo

Two Ways to Use This

This repo is an open connector layer, not the full product.

• Self-host a connector for transparency and direct control of your credentials, infrastructure, and platform access.
• Use Cesteral Intelligence when the workflow needs governed writes, team approvals, credential brokering, auditability, and cross-platform coordination — see when you need it below.

Flagship Connectors

Google Ads MCP

Campaign writes, GAQL reporting, bid adjustments, previews, and validation via Google Ads REST API v25.

Package docs | Use with Cesteral Intelligence

Meta Ads MCP

Campaign writes, insights, targeting discovery, delivery estimates, previews, and bulk operations via Meta Marketing API v26.0.

Package docs | Use with Cesteral Intelligence

DV360 MCP

Campaign writes, targeting, custom bidding, previews, uploads, and schema-driven validation via DV360 API v4.

Package docs | Use with Cesteral Intelligence

When You Need Cesteral Intelligence

The OSS connectors give you per-server tool execution + audit logs. Cesteral Intelligence layers governance and orchestration on top:

• Credential brokering -- keep platform secrets out of local operator workflows
• Approval workflows -- require human review before destructive or high-spend changes
• Aggregated audit -- unified, cross-server activity feed with provenance, tied to operator identity
• Cross-platform orchestration -- coordinate governed execution across multiple connectors
• Team operations -- shared workflows, tenant isolation, and operator visibility

Compare OSS connectors vs Cesteral Intelligence

The Full Fleet

Thirteen servers, 290+ tools. Tool counts are the live registered total per server, including the *_search_tools discovery tool where present.

What Every Server Ships

Every server speaks MCP protocol revisions 2025-03-26, 2025-06-18 and 2025-11-25, the ones @modelcontextprotocol/sdk 1.31.0 implements; the Streamable HTTP transport rejects any other MCP-Protocol-Version. The current revision, 2026-07-28, is not supported yet (#242).

That is not the whole spec. In the MCP conformance suite (@modelcontextprotocol/conformance 0.1.16) every server passes 18 of the 30 active server scenarios — initialize, ping, logging level and log notifications, tool list and call, elicitation (form, defaults and enums), resource list, read and templates, prompt list and get, concurrent SSE streams, DNS-rebinding protection — and conformance/expected-failures.yaml gives the reason for each of the other 12. Not implemented: completions, resource subscriptions, sampling, progress notifications, image / audio / embedded-resource content, and SSE stream resumption. Elicitation requests (including the destructive-action confirmations below) and log notifications are sent on the calling tools/call request's response stream, so a client does not need the optional GET stream to receive them. A server bound to a loopback address (the default outside NODE_ENV=production) accepts only loopback Host and Origin headers on /mcp; a server on any other address checks Host only when MCP_ALLOWED_HOSTS is set.

Beyond raw tool calls, every server ships:

• MCP Prompts — on-demand, multi-step workflow guidance (campaign launch, reporting, troubleshooting) so agents don't have to rediscover each platform's sequencing. Present on all 13 servers.
• MCP Resources — structured, addressable context (schemas, field catalogs, examples, enums) fetched on demand instead of bloating every tool schema. Present on all 13 servers. DV360 uses these to keep its >1 MB discriminated unions off the wire (entity-schema://, entity-fields://, entity-examples://).
• Tool discovery — a <platform>_search_tools tool that lets an agent search the server's own catalog by intent instead of paging the full list. On 10 of the 13 servers (all except the small gads-mcp and sa360-mcp / reporting-only dbm-mcp).
• Server discovery cards — SEP-2127 metadata at /.well-known/mcp/server-card.json (name, version, transports, auth modes, capabilities) on every server, in every auth mode.
• OAuth resource discovery — in jwt auth mode, the RFC 9728 endpoint at /.well-known/oauth-protected-resource.
• Report CSV spill — large report bodies spill to GCS behind a signed URL so responses stay bounded. On the six reporting-heavy servers: ttd-mcp, tiktok-mcp, snapchat-mcp, amazon-dsp-mcp, pinterest-mcp, msads-mcp.

Built for Production

Self-hosting an AI agent that touches live ad spend is a trust problem first and a capability problem second. Two things make this fleet shippable to production without hand-rolling guardrails:

• Audit-grade observability. Every tool call is captured as append-only JSONL. Failures additionally capture the full upstream HTTP trail — every request, every retry, every response — with secrets redacted at the source. Query it directly in BigQuery for hosted deployments, or pipe stdout to your existing log stack for self-host. Read the observability guide.
• Destructive-action elicitation gates. 51 destructive tools across the twelve write-capable servers (dbm-mcp is reporting-only) prompt the user before deletes, bulk status changes, bid adjustments, budget changes, conversion uploads, and async Workflows batch jobs. Stdio and clients without elicitation support fall back to a documented non-interactive contract. Bulk mutations under 10 items skip the prompt unless they touch a sensitive field (status / budget / bid).
• Verifiable release provenance. Governed tools carry a canonical SHA-256 definitionHash (from @cesteral/contract-hash) emitted into a per-package cesteral-manifest.json. Tagged releases publish to npm with build provenance, signing the manifest transitively inside the tarball, so a downstream governance system can verify exactly which tool definitions shipped and promote matching tools to attested trust.

If your security review needs evidence — the redaction list, the field schema, the upstream capture path, the contract hash — all of it is in this repository.

Quick Start

For a guided walkthrough, see the 10-minute quickstart.

Prerequisites

• Node.js >= 20.0.0
• pnpm >= 10.0.0 -- corepack enable picks up the pinned version from packageManager (or npm install -g pnpm@10)
• Docker (for containerization)
• Terraform >= 1.6.0 (for deployment)

1. Clone and install

git clone https://github.com/cesteral/mcp-open-advertising.git
cd mcp-open-advertising
pnpm install

2. Build

pnpm run build

3. Run a server locally

# Start any server using the dev script
./scripts/dev-server.sh gads-mcp    # port 3004
./scripts/dev-server.sh meta-mcp    # port 3005
./scripts/dev-server.sh dv360-mcp   # port 3002

# See each package README for required environment variables

4. Configure your AI agent

{
  "mcpServers": {
    "cesteral-gads": {
      "url": "https://gads.your-domain.com/mcp",
      "apiKey": "your-gads-api-key"
    },
    "cesteral-meta": {
      "url": "https://meta.your-domain.com/mcp",
      "apiKey": "your-meta-api-key"
    }
  }
}

Add as many servers as you need. Each runs independently and can be deployed separately.

5. Deploy

cd terraform
terraform init
terraform apply -var-file=dev.tfvars

See the deployment guide for production setup.

Architecture

Cesteral uses a GCP-native architecture with thirteen independently deployable Cloud Run MCP services. Each server exposes the MCP protocol directly via HTTPS on Cloud Run.

Key design decisions:

• Single cloud provider (GCP): Cloud Run, BigQuery, Pub/Sub, Secret Manager -- unified monitoring, ~$150-220/month
• Direct HTTP transport: No edge gateway layer needed
• Independent deployment: Each server can be deployed and scaled separately
• Composable: Use one server or all thirteen -- they work independently or together

AI clients connect directly to one or more MCP servers over HTTPS; there is no shared gateway to provision. Cesteral Intelligence, when used, layers tenancy, credentials, approvals, and governance above the same fleet.

Repository Structure

mcp-open-advertising/
├── packages/
│   ├── gads-mcp/          # Google Ads
│   ├── meta-mcp/          # Meta Ads
│   ├── dv360-mcp/         # DV360
│   ├── ttd-mcp/           # The Trade Desk
│   ├── linkedin-mcp/      # LinkedIn Ads
│   ├── tiktok-mcp/        # TikTok Ads
│   ├── cm360-mcp/         # Campaign Manager 360
│   ├── sa360-mcp/         # Search Ads 360
│   ├── pinterest-mcp/     # Pinterest Ads
│   ├── snapchat-mcp/      # Snapchat Ads
│   ├── amazon-dsp-mcp/    # Amazon DSP
│   ├── msads-mcp/         # Microsoft Ads
│   ├── dbm-mcp/           # Bid Manager (reporting)
│   ├── contract-schema/   # Shared library -- canonical annotation + response schemas
│   ├── contract-hash/     # Shared library -- canonical tool-definition hash
│   └── shared/            # Shared auth, telemetry, utilities
├── terraform/             # Infrastructure as Code
├── scripts/               # Deployment and dev automation
└── docs/                  # Documentation and guides

Development

# Install dependencies
pnpm install

# Build all packages
pnpm run build

# Run tests
pnpm run test

# Type checking
pnpm run typecheck

# Lint
pnpm run lint

Testing MCP Tools

# Use MCP Inspector
npx @modelcontextprotocol/inspector packages/gads-mcp

# Or use curl
curl -X POST http://localhost:3004/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Technology Stack

• Runtime: TypeScript 5.0+, Node.js 22 LTS, Hono (HTTP + MCP transport)
• Validation: Zod schemas
• Infrastructure: GCP Cloud Run, BigQuery, Pub/Sub, Secret Manager, Terraform
• Build: Turborepo, pnpm workspaces, Docker

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make changes and write tests
4. Run tests: pnpm run test
5. Submit a Pull Request

See also: CODE_OF_CONDUCT.md | SECURITY.md | ROADMAP.md

License

Apache License 2.0

Support

• Website: cesteral.com -- managed hosting and commercial features
• Documentation: docs/ for guides and architecture
• GitHub Issues: Report bugs or request features
• Email: [email protected]