Overview

This MCP (Model Context Protocol) server connects AI systems and agent frameworks to Improve Digital’s publisher inventory APIs. It exposes a dynamically generated set of tools based on a curated ImproveDigital Swagger description and manages OAuth2 client-credentials authentication. Agents and LLM-based assistants can list available tools, invoke inventory queries, and create or update placements programmatically, enabling automated and interactive ad operations workflows.

For developers, the server removes boilerplate: it handles token acquisition and refresh, maps API schemas into MCP tool schemas, and routes tool calls to the ImproveDigital endpoints. This lets AI tools focus on business logic — for example, reconciling inventory state or provisioning placements — instead of dealing with raw HTTP and auth.

Features

OAuth2 client credentials flow with transparent token caching and refresh
Dynamic tool generation from a curated ImproveDigital Swagger spec
Tool endpoints for listing, creating and updating publisher inventories, zones and placements
Support for multiple transports: HTTP MCP endpoint or STDIO for local AI clients
Works with MCP inspector and desktop tools like Claude and Cursor
Request/response mapping and schema resolution to produce useful tool input/output structures

Installation / Configuration

Prerequisites:

Node.js 18+
npm or yarn

Clone and install:

git clone https://github.com/azerion/improvedigital-publisher-mcp-server.git
cd improvedigital-publisher-mcp-server
npm install

Copy and edit the example environment file:

cp .env.example .env

Populate your credentials and settings in .env:

# ImproveDigital API
IMPROVE_DIGITAL_CLIENT_ID=your_client_id
IMPROVE_DIGITAL_CLIENT_SECRET=your_client_secret
IMPROVE_DIGITAL_API_BASE_URL=https://api.360yield.com
IMPROVE_DIGITAL_API_TIMEOUT_MS=60000

# Server
PORT=3000
TRANSPORT=http   # or 'stdio' for standard I/O transport

Build and run:

npm run build
npm start

Development (hot reload):

npm run dev

Run tests:

npm test

Available Tools (Generated Endpoints)

The server exposes MCP tools that correspond to ImproveDigital publisher endpoints. Key tools include:

Tool name	HTTP method	Endpoint
inventories_get_inventories	GET	/publisher/v1/publishers/{publisherId}/inventories
inventories_get_inventory_zones	GET	/publisher/v1/publishers/{publisherId}/inventories/{inventoryId}/zones
inventories_get_inventory_placements	GET	/publisher/v1/publishers/{publisherId}/inventories/{inventoryId}/zones/{zoneId}/placements
inventories_get_inventory_placement	GET	/publisher/v1/publishers/{publisherId}/inventories/{inventoryId}/zones/{zoneId}/placements/{placementId}
inventories_create_inventory_placement	POST	/publisher/v1/publishers/{publisherId}/inventories/{inventoryId}/zones/{zoneId}/placements
inventories_update_inventory_placement	PUT	/publisher/v1/publishers/{publisherId}/inventories/{inventoryId}/zones/{zoneId}/placements/{placementId}

Tool schema features:

Inputs derived from the Swagger spec (path params, query params and JSON bodies)
Outputs map API responses to structured tool outputs for agent consumption
Parameter validation and basic type coercion

Authentication

OAuth2 client credentials are provided via environment variables.
The server manages bearer tokens: it obtains tokens, caches them until expiration, and refreshes them automatically when required.
No user-interactive flows are needed; this is intended for machine-to-machine scenarios.

Integration Examples

Run locally as an HTTP MCP server and connect a client (e.g., Claude via mcp-remote):

Start server locally (PORT=3000)
Use:

{
  "mcpServers": {
    "improvedigital_mcp_server": {
      "command": "npx",
      "args": [ "mcp-remote", "http://localhost:3000/mcp", "--allow-http" ]
    }
  }
}

Run via STDIO for desktop clients that embed MCP servers (e.g., Claude Desktop):

Set TRANSPORT=stdio and launch the Node process directly.
Add a JSON config in the client pointing to the command and args that start the server process.

Cursor:

Add an MCP server entry in Cursor settings pointing to http://<MCP_SERVER>:3000/mcp and enable the tool.

Use Cases

Automate ad ops tasks: create or update placements at scale by asking an agent to reconcile desired inventory state with the actual state returned by the ImproveDigital API.
Interactive inventory inspection: let an assistant query inventories and zones and present summarized results to an operator for review.
Intelligent rule application: combine analytics from other systems with MCP tools to programmatically enable/disable placements or set targeting based on performance thresholds.
Developer tooling: use the MCP inspector to explore the generated tool schemas, test calls, and prototype agent flows without writing HTTP code.

Troubleshooting & Tips

If calls fail with auth errors, verify CLIENT_ID and CLIENT_SECRET and ensure the API base URL is correct.
Increase IMPROVE_DIGITAL_API_TIMEOUT_MS if you encounter timeouts on large responses.
Use the MCP Inspector to view available tools and parameter schemas before wiring an agent or assistant.
When integrating with desktop clients, ensure the MCP server process is accessible and that environment variables are available to the launched process.

For full code, tests and examples, consult the repository: https://github.com/azerion/improvedigital-publisher-mcp-server.

Improve Digital Publisher MCP Server AI Integration