ImproveDigital Publisher MCP Server

A Model Context Protocol (MCP) server implementation that provides access to ImproveDigital API for inventory management. The server handles OAuth authentication and exports tools to list, create and update publisher inventory. Tools are dynamically generated from a curated version of the API Swagger document.

🏗️ Architecture

┌─────────────────┐    ┌──────────────────────┐    ┌─────────────────────┐
│   MCP Client    │    │    MCP Server        │    │   API Providers     │
│                 │    │                      │    │                     │
│ • Tool Calls    │◄──►│ • Service Registry   │◄──►│ • ImproveDigital    │
│ • List Tools    │    │ • Dynamic Tools      │    │ • Swagger Docs      │  
│ • Sessions      │    │ • Schema Resolution  │    │ • OAuth Tokens      │
│                 │    │ • Authentication     │    │                     │
└─────────────────┘    └──────────────────────┘    └─────────────────────┘
                                │
                                ▼
                       ┌──────────────────────┐
                       │   Generated Tools    │
                       │                      │
                       │ • Dynamic Schemas    │
                       │ • Parameter Mapping  │
                       │ • Request Routing    │
                       │ • Response Handling  │
                       └──────────────────────┘

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn

Installation

1. Clone and install dependencies:

git clone <repository-url>
cd improvedigital-publisher-mcp-server
npm install

1. Configure environment variables:

cp .env.example .env

Edit .env with your API credentials:

# ImproveDigital API Configuration
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 Configuration
PORT=3000
TRANSPORT=http  # or 'stdio' for stdio transport

1. Build and start:

npm run build
npm start

Development Mode

npm run dev  # Hot reload with tsx

🧪 Testing

Run the comprehensive test suite:

npm test

🧪 Using in MCP inspector

Run the MCP Inspector UI, then follow instructions:

npx @modelcontextprotocol/inspector

🧪 Using in Claude (as STDIO)

• Create the file claude_desktop_config.json with the following content:

{
  "mcpServers": {
    "improvedigital_mcp_server": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/your/path/to/improvedigital-publisher-mcp-server/dist/src/index.js"
      ],
      "env": {
        "IMPROVE_DIGITAL_CLIENT_ID": "...",
        "IMPROVE_DIGITAL_CLIENT_SECRET": "...",
        "IMPROVE_DIGITAL_API_BASE_URL": "https://api.360yield.com",
        "IMPROVE_DIGITAL_API_TIMEOUT_MS": "60000",
        "TRANSPORT": "stdio"
      }
    }
  }
}

For mac the path is: ~/Library/Application\ Support/Claude/claude_desktop_config.json For windows the path is: C:\Users\[YourUsername]\AppData\Roaming\Claude\claude_desktop_config.json

• Build the tool as described above.

• Launch Claude desktop (or restart if already running)

🧪 Using in Claude (as HTTP)

• Create the file claude_desktop_config.json with the following content:

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

For mac the path is: ~/Library/Application\ Support/Claude/claude_desktop_config.json For windows the path is: C:\Users\[YourUsername]\AppData\Roaming\Claude\claude_desktop_config.json

• Run the mcp server in local machine and use value of <MCP_SERVER> as localhost. Or, use value of <MCP_SERVER> as any existing deployment host.

• Launch Claude desktop (or restart if already running)

🧪 Using in Cursor

• Add new MCP server (Settings => MCP Tools => New MCP Server) with the following content:

{
  "mcpServers": {
    "improvedigital_mcp_server": {
      "url": "http://<MCP_SERVER>:3000/mcp"
    }
  }
}

• Run the mcp server in local machine and use value of <MCP_SERVER> as localhost. Or, use value of <MCP_SERVER> as any existing deployment host.

• Enable the tool.

Authentication

• OAuth2 Client Credentials provided via environment variables
• Bearer token management, token expiration handling

🛠️ Generated Tools

• 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

• Path Parameters: Automatically extracted and validated (e.g., {publisherId})
• Query Parameters: Optional and required parameters with type validation
• Request Bodies: JSON schema generation from OpenAPI specifications
• Schema References: Full $ref resolution with circular reference protection

🔧 Configuration

Transport Modes

HTTP Transport (Production):

TRANSPORT=http
PORT=3000

Access via: http://localhost:3000/mcp

Stdio Transport (Development):

TRANSPORT=stdio

Usage examples

Once the MCP server is successfully installed into your AI tool you can start managing inventory with your prompts.

Example 1: List all inventories

List all inventories for publisher 1816

Example 2: View zones in an inventory

Show me all zones under inventory 346036

Example 3: List placements in a zone

List all placements in zone 17087058 under inventory 346036

Example 4: Create a new placement

Create a new video preroll placement in zone 17087058 under inventory 346036.
Name it "Test Placement", set player size to 640x480, duration 1-30 seconds.

Example 5: Copy an existing placement

Copy placement 22376222 and name it "My New Placement"

Example 6: Update a placement

Update placement 22376237 to change the name to "Updated Placement Name"

Programmatic use

It is also possible to use the module embedded into third party applications like custom agents. For this the module exports the createMcpContext function that initializes the MCP tools and creates an MCP server instance. Here is an example of possible usage:

import { createMcpContext } from "@improvedigital/publisher-mcp-server";

// Initialize agent tools
const improveMcpContext = await createMcpContext({
  improveDigitalClientId: process.env.IMPROVE_DIGITAL_CLIENT_ID!,
  improveDigitalClientSecret: process.env.IMPROVE_DIGITAL_CLIENT_SECRET!,
});
const mcpClient = await initializeMcpConnection(improveMcpContext.mcpServer);
const improveTools = improveMcpContext.mcpTools.map(tool => convertMCPToolToLangChain(tool, mcpClient));

// Initialiaze agent
...

License

This project is licensed under the MIT License - see below for details.

MIT License

Copyright (c) 2025 ImproveDigital

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🔗 Related Documentation

• MCP Protocol - Model Context Protocol specification
• OpenAPI Specification - API documentation standard