Mindify Ads MCP Integration for Agent Hosts

Mindify Ads exposes a streamable Model Context Protocol (MCP) server that allows AI agents to dynamically discover and invoke advertising tools over HTTP. This enables agents to serve relevant, contextual ads at runtime without embedding ad logic directly into models or application code.

Mindify Ads centralizes ad targeting, fraud detection, and reporting while keeping agent integrations simple and MCP-native.

To support advertising targeting and fraud prevention, every MCP request must include the end-user’s IP address and User-Agent, along with your Mindify Ads secret for authentication.

What Mindify Ads Enables

With Mindify Ads, your agent can:

  • Retrieve contextual advertising tools during reasoning
  • Serve ads dynamically without hard-coded integrations
  • Rely on Mindify for targeting, fraud detection, and policy enforcement
  • Integrate using standard MCP over HTTP

If your agent host already supports MCP, integration is primarily configuration.

Data & Privacy Model

Mindify Ads requires limited network metadata to operate safely and effectively.

Collected data

  • IP address — used for geographic targeting and fraud detection
  • User-Agent — used for device targeting and abuse prevention

Important notes

  • The IP address and User-Agent must come from the end-user client, not your server
  • Do not proxy, mask, or substitute these values
  • Mindify Ads does not require personally identifiable information (PII) beyond network metadata
  • Metadata is used strictly for advertising delivery, targeting, and fraud prevention

Before You Write Code

  1. Register for Mindify Ads
  2. Activate your AI agent host
  3. Create your AI platform in the dashboard
  4. Generate a secret key and store it securely
    • Never expose this secret to clients
    • Rotate secrets regularly

Request Flow

  1. End-user interacts with your client (browser, mobile app, etc.)
  2. Client provides IP address and User-Agent
  3. Your Agent:
    • Builds the `mindify-mcp-metadata` header
    • Attaches the Authorization header
  4. Agent connects to Mindify Ads MCP over HTTP
  5. Agent discovers available advertising tools
  6. Agent invokes ad tools during reasoning

Connection Details

MCP endpoint

https://api.mindifyai.dev/api/v1/mcp
  • Authorization header

`Authorization: Bearer YOUR_SECRET`

  • Metadata header

`mindify-mcp-metadata: <base64-encoded networkInfo payload>`

Test / Development Secrets

Use these secrets during development and CI. These secrets do not perform real targeting, do not generate billable impressions, and are safe to use in non-production environments.

No Ad Response

test-not-found

MCP returns no ad response.

Test Ad Response

test-ad

MCP returns a deterministic test ad response.

Building the mindify-mcp-metadata Header

Each MCP request must include a `mindify-mcp-metadata` header containing the end-user’s network information.

Required structure

{  "networkInfo": {    "userIpAddress": "string",    "userAgent": "string"  }}

Encoding requirements

The header value must be:

  1. JSON-encoded
  2. UTF-8 encoded
  3. Base64 encoded

TypeScript Example

import { Buffer } from "node:buffer";const MINDIFY_MCP_URL = "https://api.mindifyai.dev/api/v1/mcp";function buildMetadataHeader(userIpAddress: string, userAgent: string): string {  const metadata = {    networkInfo: {      userIpAddress,      userAgent,    },  };  return Buffer.from(JSON.stringify(metadata)).toString("base64");}const headers = {  Authorization: `Bearer ${mindifyAdsSecret}`,  "mindify-mcp-metadata": buildMetadataHeader(    userIpFromClient,    userAgentFromClient  ),};

Common Mistakes

⚠️ Avoid the following:

  • Sending your server IP instead of the end-user IP
  • Omitting base64 encoding
  • Modifying the JSON structure
  • Reusing metadata across different users
  • Storing metadata as a global or static header

Each request must reflect the current end-user.

Integration Examples

Each example follows the same pattern:

  1. Load the Mindify Ads secret
  2. Build the metadata header from end-user context
  3. Connect to Mindify Ads MCP over HTTP
  4. Allow the agent to discover and invoke tools

Prerequisites

npm install @anthropic-ai/sdk @modelcontextprotocol/sdk dotenv
import { Anthropic } from "@anthropic-ai/sdk";import { Client } from "@modelcontextprotocol/sdk/client/index.js";import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";import { config } from "dotenv";const MINDIFY_MCP_URL = "https://api.mindifyai.dev/api/v1/mcp";export async function run(  promptText: string,  userIpAddress: string,  userAgent: string) {  config();  const mindifyAdsSecret = process.env.MINDIFY_ADS_SECRET ?? "";  const anthropicApiKey = process.env.ANTHROPIC_API_KEY ?? "";  // defined above  const metadata = buildMetadataHeader(userIpAddress, userAgent);  const client = new Client({    name: "mcp-client",    version: "1.0.0",  });  const transport = new StreamableHTTPClientTransport(    new URL(MINDIFY_MCP_URL),    {      requestInit: {        headers: {          Authorization: `Bearer ${mindifyAdsSecret}`,          "mindify-mcp-metadata": metadata,        },      },    }  );  const anthropic = new Anthropic({ apiKey: anthropicApiKey });  await client.connect(transport);  const toolsResult = await client.listTools();  // ... use tools with LLM ...  return "Response";}

Operational Considerations

  • Cache tool lists when possible to reduce latency
  • Rotate Mindify Ads secrets regularly
  • Never expose secrets to end-users
  • Always send per-request metadata
  • Validate IP and User-Agent at your client boundary

Getting Help

If you encounter integration issues, contact support@mindifyai.dev