HyperMindz Agency MCP · Developer docs

One protocol. Every ad platform.

A production Model Context Protocol server for multi-platform campaign orchestration. Plan, build, launch, optimize and measure across 12 ad platforms — through one standards-based interface, 62 clean v2 tools, and a catalog of ready-made skills.

Get started Browse the 62 tools Skills catalog

first call — no auth required

curl -s https://relay-mcp.hypermindz.ai/api/health

{ "status": "healthy",
  "service": "hypermindz-agency-mcp",
  "version": "1.0.0" }

Overview

One client speaks one protocol; the server fans out.

Instead of integrating each ad platform's API separately, a client speaks one protocol (MCP / JSON-RPC 2.0) to one server, and the server orchestrates the underlying DSPs and SSPs — brief and proposal generation, campaign / strategy / targeting setup, deal and inventory discovery, validation and activation, bid / budget / pacing optimization, and cross-platform performance, attribution and reporting.

Demand-side9 DSPs

Google Ads
Meta Ads
LinkedIn Ads
TikTok Ads
The Trade Desk
DV360
Amazon DSP
MediaMath / Infillion
Vistars

Supply-side3 SSPs

Media.net
Nexxen
Index Exchange

Not every tool applies to every platform. Where a capability is platform-specific (e.g. DV360 line items, SSP deal scoring), the tool schema and the live capability matrix say so.

Quickstart

From zero to your first tool call.

01

Confirm the server is up

No auth required.

curl -s https://relay-mcp.hypermindz.ai/api/health

02

Add the server to your MCP client

Point any OAuth-capable client (Claude, Cursor, MCP Inspector) at the endpoint. It discovers auth and signs you in automatically.

https://relay-mcp.hypermindz.ai/mcp

03

Make your first call

List the tools, then call healthcheck.

{ "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": {
    "name": "healthcheck",
    "arguments": {} } }

Choose your path

Three readers, one reference.

Integrator

Wiring an MCP client or agent to the server.

Quickstart → Authentication → Protocol → v2 Tools

Agent author

Building prompts / workflows on the tools.

Lifecycle → Skills → Recipes → v2 Tools

Evaluating

Deciding whether to adopt.

Overview → Platform coverage → Security → Versioning

Authentication & connection

OAuth 2.1 protected resource — no static API keys.

The server does not issue its own passwords or tokens to external clients. Authentication is delegated to our authorization server using the Authorization Code flow with PKCE (S256) — the standard MCP pattern, so compliant clients handle it automatically. Access is granted per organization.

How to request access →

Protocol basics

MCP 0.1.0 over JSON-RPC 2.0.

Methods

initialize	Open a session, negotiate capabilities
tools/list	List tool definitions (name, schema, annotations)
tools/call	Execute a tool
prompts/list	List / fetch prompt templates
ping · shutdown	Liveness · close session

resources/list returns an empty set in this version.

Every tool returns dual-format

{
  "content": [{ "type": "text",
                "text": "Found 3 campaigns" }],
  "structuredContent": {
    "data": [ /* typed items */ ],
    "meta": { "pagination": {
      "nextCursor": "…", "hasMore": true } }
  },
  "isError": false
}

readOnlyHint
destructiveHint
idempotentHint
openWorldHint

List tools return at most 25 items per page. Pass the opaque base64 nextCursor back as cursor to page.

Onboarding

Two steps to go live: get access, then connect your platforms.

There are two distinct kinds of onboarding — getting access to the MCP itself, and connecting your ad platforms to it. Do the first once per organization; the second per platform you want to run through the server.

1 · Platform access

Get access to the MCP

Access is granted per organization. Request it below and we provision a dedicated OAuth client for your org. You then connect any OAuth 2.1 + PKCE capable MCP client (Claude, Cursor, MCP Inspector) — it signs you in automatically against our authorization server; no secrets to handle.

Request access → we provision your org's OAuth client
Connect your MCP client via OAuth 2.1 + PKCE (S256)
Create agencies & advertisers, invite teammates with roles

2 · Platform credentials

Connect your ad platforms

Two options per platform. Credentials are stored encrypted, per tenant (org-shared or personal), and resolved from your verified token — connect once and every campaign tool can reach the platform.

Bring your own keys— provide each platform's API key / secret
OAuth— authorize on the platform; we securely store & auto-refresh your refresh tokens
Test every connection before you push a campaign

platform_integration_set · oauth_initiate · oauth_callback · platform_connection_test · check_integration_health

The campaign lifecycle

Six phases. The tools are named to match.

For agent authors this is the most useful mental model — most real workflows are a walk through these phases.

BRIEF

Turn an objective into a structured brief + proposal

brief_generate · proposal_generate · proposal_approve

PLAN

Build the execution plan; source inventory and deals

plan_generate · deal_available_list · deal_list

SETUP

Create campaigns, strategies, creatives, targeting

proposal_execute · strategy_create · targeting_apply

ACTIVATE

Validate readiness and go live

campaign_validate · campaign_activate · campaign_pause

OPTIMIZE

Improve performance while running

optimization_recommend · bid_adjust · budget_reallocate

MEASURE

Report, attribute, and analyze results

campaign_performance_get · report_generate · benchmark_compare

The v2 tool surface

62 clean, consistent tools.

One naming convention ({domain}_{action}), one read verb per cardinality (_list / _get), payload-driven writes, and honest annotations. This is the recommended surface for external clients. The full server exposes 250+ tools — call tools/list for the authoritative live set with schemas.

Select any tool for its full description, parameters, and an example call.

System

Server health & connectivity

Organizations & access

Organizations the caller can access

Advertisers, filtered by org

Platform onboarding

Connected DSP/SSP integrations + state

Connect / update a platform (BYOK)

Remove a platform integration

Test auth/connectivity before a push

Which platforms are configured & valid

Brief & plan

Structured brief from a plain objective

Media proposal from a brief

Approve a proposal for execution

Create the campaign + strategies (DB)

Refresh the execution plan only

Campaigns

List / search campaigns

One campaign + metrics + sync status

Push an existing campaign to platforms

The single campaign mutation path

Dry-run readiness check

Activate across targeted platforms

Pause a running campaign

Delete a campaign + its strategies

Strategies

List strategies for a campaign/advertiser

One strategy (+ targeting / creatives)

Create a strategy within a campaign

Update strategy fields via payload

Delete a strategy + remove from platforms

Targeting

Apply targeting + assign creatives, per platform

Read current strategy targeting

Creatives & concepts

Creative concepts for an advertiser

Create a concept (optionally on MediaMath)

Delete a concept

Creatives for an advertiser

Create a creative + assign to a strategy

Update a creative

Reassign a creative to a strategy

Delete a creative

Audiences

Audience segments for an advertiser

One audience segment

Create an audience segment

Update an audience segment

Delete an audience segment

Deals

Search the full deal catalog

One deal by id

Deals ready to attach

Create a deal

Update a deal

Attach a deal to a strategy

Push a deal to external DSPs

Delete a deal

Optimize

AI recommendations to improve performance

Quick single-strategy bid change

Change a strategy's pacing type/amount

Redistribute budget across strategies

Pacing health, projections, recs

Measure

Real campaign metrics from the platform

Real strategy metrics

Video quartiles & completion

Viewability metrics

Conversion attribution

Compare vs industry / historical

Formatted report for one entity

Roll-up across multiple campaigns

Ad-ops skills catalog

19 skills that drive the tools.

Skills bundle the tools into role-based workflows — the operator's view rather than the integrator's. Each one routes on its own trigger phrases.

Campaign lifecycle

agency-mcpon-demand

Build & launch a campaign end-to-end (brief → activate).

brief_generate · proposal_* · campaign_push · targeting_apply · campaign_activate

campaign-brief-builderon-demand

Objective / RFP / Salesforce opp → structured brief + proposal.

brief_generate · proposal_generate · salesforce_create_brief_from_opportunity

media-plan-architecton-demand

Budget allocation, flighting, platform mix, deal sourcing.

proposal_generate · plan_generate · deal_available_list

creative-opson-demand

Create, validate, generate & traffic concepts and creatives.

concept_create · creative_create · creative_validate_specs · creative_assign

campaign-qaon-demand

Pre-launch readiness audit across the whole campaign.

campaign_validate · targeting_get · creative_list

Optimize & measure

campaign-optimizerboth

Read performance, surface recs, apply bid / pacing / budget changes.

campaign_performance_get · optimization_recommend · bid_adjust · budget_reallocate

pacing-watchdogscheduled

Daily delivery/budget anomaly detection + alerts.

pacing_analysis_get · get_dashboard_alerts

performance-reporterboth

Client-facing performance reports & executive summaries.

campaign_performance_get · report_generate · executive_summary_generate

attribution-analyston-demand

Conversion attribution, lift, cross-channel reach.

attribution_get · viewability_get · video_performance_get

portfolio-dashboardboth

Cross-campaign portfolio health rollup for an advertiser/org.

get_portfolio_summary · get_dashboard_alerts · campaign_list

Supply & audiences

deal-scoutboth

Discover, score, and attach programmatic deals; sync to DSPs.

deal_available_list · ssp_score_deal · deal_attach · deal_sync

audience-builderon-demand

Create / import / activate audience segments across platforms (BYOK).

audience_create · activate_audience_segments · sync_platform_audiences

inventory-curatoron-demand

SSP inventory discovery, capabilities, domain/URL/IP lists.

ssp_query_inventory · ssp_list_capabilities · ssp_*_group

Onboarding & admin

platform-credentialson-demand

Connect/manage DSP+SSP credentials: list, connect, test, remove.

set_platform_integration · test_platform_connection · oauth_initiate/callback

platform-onboardingon-demand

Self-service setup: credentials + advertisers/agencies + invite team.

platform-credentials + create_advertiser · create_agency · create_user

integration-healthboth

Monitor connections; surface needs_reauth / expired; test.

check_integration_health · test_platform_connection · get_platform_integrations

platform-onboarding-adminon-demand

Provision org access, advertisers, and team invites.

create_advertiser · create_agency · create_user

Verification & cross-DSP

mediamath-mcpon-demand

Verify campaign/strategy/creative state on the MediaMath T1 API.

MediaMath MCP

cross-platform-verifyon-demand

Verify a campaign's state across all targeted DSPs.

per-platform *_get / list + sync-status tools

Use it in Claude

Connect the MCP, then just ask.

Add the Agency MCP as a connector in any MCP-capable Claude client and sign in once (OAuth 2.1 + PKCE). Claude can then call the tools directly. Layer the ad-ops skills on top for role-based, one-phrase workflows.

01

Connect the server

Point your client at the MCP endpoint — it walks you through sign-in.

Claude Code

claude mcp add --transport http \
  agency-mcp https://relay-mcp.hypermindz.ai/mcp

claude.ai / Claude Desktop — Settings → Connectors → Add custom connector → URL:

https://relay-mcp.hypermindz.ai/mcp

02

Install the skills

The ad-ops skills bundle the tools into role-based workflows (HyperMindz + partner access). Symlink one — or all — into Claude's skills dir.

git clone \
  github.com/Hypermindz-AI/claude-skills

ln -s "$PWD/claude-skills/campaign-optimizer" \
  ~/.claude/skills/campaign-optimizer

Restart Claude Code; the skill auto-routes on its trigger phrases.

03

Talk to it

Ask in plain language — the connected tools (and any installed skill) do the rest.

"Build a brief for a $50k CTV
campaign, then optimize pacing
once it's live."

Guides & recipes

Tools are building blocks; real work is a sequence.

Launch a campaign end-to-end

brief_generate → proposal_generate → proposal_approve → proposal_execute → strategy_create → targeting_apply → campaign_validate → campaign_activate

Generate a platform-aware proposal

proposal_generate(platform: "mediamath") → adds targeting with geo/device IDs, frequency caps, matched deals and an execution_ready flag

Discover and attach deals

deal_available_list → deal_get → deal_attach → deal_sync → get_deal_sync_status

Measure and optimize

campaign_performance_get → optimization_recommend → bid_adjust / budget_reallocate → report_generate

Security, isolation & limits

Tenant-scoped by the verified token — never by client input.

Every request is scoped to the caller's organization, resolved from the verified OAuth token. A token for one organization cannot read or modify another's data. Role-based access control further constrains each user: canonical roles are ADMIN, MANAGER, TRADER, ANALYST, VIEWER and PLATFORM_ADMIN — read-only callers cannot invoke write or destructive tools.

Limits

Pagination	Max 25 items per page
Session TTL	24 hours
Auth	OAuth 2.1 + PKCE (S256)
Transport	HTTPS only
Protocol	MCP 0.1.0 over JSON-RPC 2.0

Errors

Errors follow the JSON-RPC 2.0 shape:

{ "jsonrpc": "2.0", "id": 1,
  "error": { "code": -32001,
             "message": "Authentication required" } }

Situation	What you'll see
Missing / invalid token	401 — invalid_token / "Authentication required"
Calling a retired endpoint	410 Gone — use /mcp
Unknown method	JSON-RPC -32601 (method not found)
Bad tool arguments	JSON-RPC error with validation detail in data

Glossary

The vocabulary, once.

MCP

Model Context Protocol — open standard for connecting AI clients to tools & data.

DSP

Demand-Side Platform — where advertisers buy ad inventory.

SSP

Supply-Side Platform — where publishers sell ad inventory.

Campaign

Top-level container for an advertising effort.

Strategy

A targeting + bidding configuration within a campaign.

Concept / Creative

The ad content and its platform-specific renditions.

Deal

A negotiated inventory agreement (e.g. PMP) sourced from an SSP / exchange.

Brief / Proposal

Structured statement of campaign objectives and the recommended plan.

PKCE

Proof Key for Code Exchange — OAuth extension securing the auth-code flow.

Versioning & support

The v2 surface is the contract.

tools/list is the authoritative, live set — always prefer it over any published list, including this page. Breaking changes to the v2 surface are announced before they ship.

Request access →Talk to us