AdsMCP Integration: Setup & Configuration

Overview

AdsMCP is Adgentek’s fully managed Model Context Protocol server that enables AI applications to serve contextual advertisements. It automatically selects and serves relevant ads based on conversation context, user intent, and placement opportunities.

Because the server is fully hosted by Adgentek, there is no infrastructure to maintain, no scaling to manage, and no tracking to implement. You configure your MCP client, call the provided tools, and Adgentek handles the rest.

Quick Reference

MCP Server URL	https://mcp.adgentek.ai/mcp
Authentication	Bearer token (adgt_ prefixed API key)
Primary Tool	ads.serve
Tracking	Fully automatic (impressions, clicks, conversions)
Infrastructure	Fully managed — no servers to maintain

Prerequisites

Before starting the integration, make sure you have the following:

An active Adgentek publisher account
A Publisher API key with the adgt_ prefix (create or manage keys in your Adgentek dashboard)
An AI application or platform that supports the Model Context Protocol (MCP)
Access to your MCP client’s configuration file

Step 1: Configure Your MCP Client

Add the Adgentek MCP server to your AI application’s configuration. The exact file location depends on your platform (see the Platform-Specific Setup section for details).

{

"mcpServers": {

"adgentek-ads": {

"url": "https://mcp.adgentek.ai/mcp",

"headers": {

"Authorization": "Bearer adgt_YOUR_API_KEY_HERE"

}

Security Reminder

Keep your API keys secure. Store them in environment variables or a secrets manager where possible. Never commit keys to version control or expose them in client-side code.

Step 2: Call ads.serve in Your AI Application

Once configured, your AI application can call the ads.serve MCP tool with conversation context. The server analyzes the conversation for user intent, sentiment, topic relevance, and engagement signals, then returns a contextually matched ad.

const result = await callTool('ads.serve', {

messages: [

{ role: 'user', content: 'What are the best practices for React hooks?' },

{ role: 'assistant', content: 'React hooks are functions that let you use state...' },

{ role: 'user', content: 'Can you explain useEffect in more detail?' }

surface: 'conversational',

sessionId: 'session_' + sessionId,

userKey: 'user_' + userId

});

if (result.ad) {

// Display the ad — tracking is fully automatic

displayAd(result.ad);

// Pre-formatted render output available:

// result.ad.render.markdown

// result.ad.render.html

// result.ad.render.plain

}

ads.serve Parameters

Parameter	Type	Required	Description
messages	array	Yes	Conversation history as role/content pairs. Send the most recent messages (up to 10) for best targeting.
surface	string	Yes	The ad surface type: conversational, search, voice, creative, or web.
sessionId	string	Yes	Stable session identifier for frequency capping and deduplication.
userKey	string	No	Optional user identifier for cross-session frequency capping and personalization.
intent	string	No	Override the auto-detected intent: purchase, research, support, or informational.
depth	string	No	Conversation depth hint: shallow, mid, or deep.
placementCandidates	array	No	List of eligible placement positions in your UI.

Step 3: Verify Integration

Once you’ve integrated and tested ads.serve in your development environment, contact hello@adgentek.ai to verify your integration and go live with real ads.

Before Going Live

The Adgentek team will review your integration to confirm that ad requests are well-formed, tracking is functioning correctly, and ads are rendering as expected. This step ensures the best experience for both your users and advertisers.

Available MCP Tools

The Adgentek MCP server exposes four tools. The primary tool for serving ads is ads.serve. The remaining tools support performance optimization, configuration, and debugging.

Tool	Category	Description
ads.serve	Primary	Serves contextual ads based on conversation context, user intent, and placement opportunities. Automatically tracks impressions server-side.
ads.prefetch	Performance	Batch-request multiple ads for caching and improved performance. Useful when you know upcoming conversation contexts in advance.
ads.config	Configuration	Retrieves publisher configuration, slot settings, and ad policies. Use to adapt your application behavior based on your account settings.
ads.diagnostics	Debug	Provides debugging information about ad eligibility, targeting, filtering reasons, and auction logs. Use when ads are not serving as expected.

ads.prefetch — Batch Request Multiple Ads

Use ads.prefetch to request ads for multiple conversation contexts in a single call. This is useful for pre-caching ads at known interaction points like welcome screens, support flows, or product pages.

const prefetchResults = await callTool('ads.prefetch', {

batch: [

{

messages: [{ role: 'user', content: 'How do I get started?' }],

surface: 'conversational',

sessionId: 'welcome_' + sessionId

{

messages: [

{ role: 'user', content: 'I need help with my account' },

{ role: 'assistant', content: 'I\'d be happy to help...' }

surface: 'conversational',

sessionId: 'support_' + sessionId

}

]

});

// Cache results for later use

prefetchResults.ads.forEach((ad, index) => {

if (ad) cache.set(`prefetch_${index}`, ad, 300);

});

ads.config — Get Publisher Configuration

Use ads.config to retrieve your publisher settings, available slots, and ad policies. This is useful for adapting your application behavior at startup or when checking slot capabilities.

const config = await callTool('ads.config', {

includeSlots: true,

includePolicies: true,

includeAnalytics: false

});

console.log('Publisher info:', config.publisher);

console.log('Available slots:', config.slots);

console.log('Ad policies:', config.policies);

// Check slot capabilities

config.slots.forEach(slot => {

console.log(`Slot ${slot.id} supports:`, slot.capabilities);

if (slot.capabilities.supportsVoice) enableVoiceAds(slot.id);

if (slot.capabilities.supportsSidebar) enableSidebarAds(slot.id);

});

Parameter	Type	Required	Description
includeSlots	boolean	No	Include slot configurations in the response. Defaults to false.
includePolicies	boolean	No	Include ad policies (brand safety, frequency caps). Defaults to false.
includeAnalytics	boolean	No	Include recent analytics summary. Defaults to false.

ads.diagnostics — Debug Ad Eligibility

Use ads.diagnostics when ads are not serving as expected. This tool returns detailed information about why ads were filtered, including geographic mismatches, frequency caps, exhausted budgets, and auction results.

const diagnostics = await callTool('ads.diagnostics', {

messages: [

{ role: 'user', content: 'Tell me about electric vehicles' },

{ role: 'assistant', content: 'Electric vehicles are becoming...' }

surface: 'conversational',

sessionId: 'debug_' + sessionId,

checkEligibility: true,

includeAuctionLog: true

});

console.log('Eligible ads:', diagnostics.eligibleAds?.length || 0);

console.log('Filtered ads:', diagnostics.filteredAds?.length || 0);

// Review filtering reasons

diagnostics.filteredAds?.forEach(ad => {

console.log(`Ad "${ad.title}" filtered:`, ad.filterReasons);

});

// Review auction log

if (diagnostics.auctionLog) {

console.log('Winner:', diagnostics.auctionLog.winner);

console.log('Total bids:', diagnostics.auctionLog.totalBids);

console.log('Floor price:', diagnostics.auctionLog.floorPrice);

}

Common Filter Reasons

Filter Reason	What It Means
geo_mismatch	The user’s geographic location does not match the campaign’s targeting settings.
frequency_capped	The user has already been shown this ad the maximum number of times allowed.
budget_exhausted	The campaign’s budget has been fully spent for the current period.
brand_safety	The conversation context was flagged by brand safety filters.
no_matching_intent	The detected user intent does not match any active campaign targeting.

Automatic Tracking Architecture

No Manual Tracking Required

Adgentek controls all tracking end-to-end for security and fraud prevention. Publishers do not need to report events and cannot manipulate tracking data.

Tracking Type	How It Works
Impressions	Tracked via the pixel URL in ad.impression_url. Render as an <img> tag or fire a GET request. Server-side impression tracking is also performed when ads.serve returns an ad.
Clicks	All ad URLs route through Adgentek’s click-redirect service. The click is logged before the user is forwarded to the advertiser’s landing page.
Conversions	Handled through advertiser-side pixels and server-to-server postback URLs. No publisher action required.

Platform-Specific Setup

The MCP configuration format varies slightly depending on which platform or IDE you are using. Below are the config file paths and JSON formats for the most common platforms.

Claude Desktop

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json

{

"mcpServers": {

"adgentek-ads": {

"url": "https://mcp.adgentek.ai/mcp",

"headers": {

"Authorization": "Bearer adgt_YOUR_API_KEY_HERE"

}

Claude for Code (VS Code Extension)

Config file: .vscode/settings.json

{

"claude.mcpServers": {

"adgentek-ads": {

"url": "https://mcp.adgentek.ai/mcp",

"headers": {

"Authorization": "Bearer adgt_YOUR_API_KEY_HERE"

}

VS Code MCP Extension

Config file: .vscode/settings.json

{

"mcp.servers": {

"adgentek-ads": {

"url": "https://mcp.adgentek.ai/mcp",

"headers": {

"Authorization": "Bearer adgt_YOUR_API_KEY_HERE"

}

Cursor AI IDE

Config file: ~/.cursor/mcp.json

{

"mcpServers": {

"adgentek-ads": {

"url": "https://mcp.adgentek.ai/mcp",

"headers": {

"Authorization": "Bearer adgt_YOUR_API_KEY_HERE"

}

Best Practices

Practice	Guidance
Message Context	Send the most recent 10 messages to ads.serve for the best targeting accuracy. Trim older messages to keep payloads efficient.
Surface Type	Always set the surface parameter accurately. This determines which ad creatives are eligible and how they should render.
Session Management	Use a stable sessionId per user session. This enables proper frequency capping and deduplication. Do not regenerate per request.
Prefetching	Use ads.prefetch for known interaction points (onboarding, support, product pages) to reduce latency and improve ad fill rates.
Error Handling	Always handle the case where no ad is returned. Your application should function normally with or without an ad response.
Diagnostics	Use ads.diagnostics during development and integration testing to understand why ads are or are not serving for a given context.
Security	Store API keys in environment variables or a secrets manager. Never hardcode keys in source code or expose them in client-side bundles.

Troubleshooting

Issue	Resolution
MCP connection failed	Verify the server URL is correct: https://mcp.adgentek.ai/mcp. Check that your API key starts with adgt_ and is included in the Authorization header as a Bearer token.
401 Unauthorized	Your API key is invalid, expired, or missing. Regenerate it in the Adgentek dashboard and update your MCP client config.
No ad returned	This is normal — not every request returns an ad. Use ads.diagnostics to check eligibility, targeting, and filtering reasons.
Ads not contextually relevant	Send more conversation messages in the messages array. At least 2–3 message pairs gives the server enough context for accurate targeting.
Config not picked up	Restart your MCP client (IDE, desktop app) after changing the configuration file. Most clients do not hot-reload MCP server configs.
Slow ad responses	Use ads.prefetch to batch-request ads for predictable conversation flows. Check your network latency to api.adgentek.ai.

Need Help?

If you run into issues or have questions about the AdsMCP integration, reach out to the Adgentek publisher support team at support@adgentek.ai. When contacting support, include your publisher ID, the platform you are integrating with, example request/response payloads, and any error messages or diagnostics output.

AdsMCP Integration: Setup & Configuration

Connect your AI application to Adgentek’s hosted MCP server and start serving contextual ads in minutes

Overview

Quick Reference

Prerequisites

Step 1: Configure Your MCP Client

Step 2: Call ads.serve in Your AI Application

ads.serve Parameters

Step 3: Verify Integration

Available MCP Tools

ads.prefetch — Batch Request Multiple Ads

ads.config — Get Publisher Configuration

ads.diagnostics — Debug Ad Eligibility

Automatic Tracking Architecture

Platform-Specific Setup

Claude Desktop

Claude for Code (VS Code Extension)

VS Code MCP Extension

Cursor AI IDE

Best Practices

Troubleshooting

Need Help?