ADP API MCP Documentation Server

MCP (Model Context Protocol) server providing GraphQL schema documentation, query examples, and intelligent search capabilities for GraphQL APIs. Designed to help AI assistants learn and use GraphQL APIs more effectively.

Features

• Practical User Guides: Step-by-step workflows and real-world examples for common tasks
  • Creating advertising campaigns (Deal → Line Item → Creative)
  • Managing audience segments
  • Generating reports and statistics
  • Authentication and setup
  • CRM/OMS integration workflows
  • Best practices and gotchas
• Schema Documentation: Retrieve complete GraphQL type definitions with fields, descriptions, and deprecation warnings
  • Automatic documentation of JSON parameter formats (filter, sort)
  • Connection type metadata explaining custom structure
  • Inline hints for complex parameters
• Intelligent Search: Find types, operations, and fields by partial name with relevance scoring
  • Perfect for AI agents building queries from scratch
  • Returns full operational context with example queries
• Query Examples: Access executable GraphQL queries with variables from tests and production code
  • Auto-generated examples for operations without real-world examples
  • Three complexity levels: simple, medium (with filter), advanced (with filter + sort)
• Query Execution: Test and validate GraphQL queries against live API
  • Read-only query execution (mutations blocked)
  • Built-in validation and error detection
• Common Patterns: Comprehensive documentation of API usage patterns
  • Filter operators and examples (=, !=, >, <, >=, <=, in, like)
  • Sorting patterns (asc/desc - case-sensitive!)
  • Pagination strategies (limit/offset)
  • Connection type structure (custom, without 'node' wrapper)
• Common Mistakes: Learn from typical API usage errors
  • Critical mistakes with corrections
  • Sort direction case sensitivity warnings
  • Connection structure pitfalls
• Domain Organization: Browse by API domains (DAS, CRM, Video, MIA)
  • Top operations by usage frequency
  • Domain-specific pattern summaries
• Usage Frequency: See which operations are most commonly used in production
• Deprecation Detection: Identify deprecated types and operations, check if still in use

Installation

npm install -g @slawomirjach/adpapi-mcp-server

Or use with npx (no installation):

GRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \
GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \
GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \
npx @slawomirjach/adpapi-mcp-server

Quick Start

For Claude Code Users (Recommended)

# One command to add MCP server (with authentication via environment variables)
claude mcp add --transport stdio adpapi-docs \
  --env GRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \
  --env GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \
  --env GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \
  -- npx @slawomirjach/adpapi-mcp-server

# Verify it works
claude mcp list

Then use in Claude Code:

• Type /mcp to check server status
• Ask: "What operations are available in my GraphQL API?"
• The server will automatically provide schema documentation and examples

Standalone Usage

# Install globally
npm install -g @slawomirjach/adpapi-mcp-server

# Run with your GraphQL endpoint (with authentication via environment variables)
GRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \
GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \
GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \
adpapi-mcp-server

# Or use npx (no installation needed)
GRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \
GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \
GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \
npx @slawomirjach/adpapi-mcp-server

Configuration

Environment Variables (Required)

The server is configured entirely through environment variables for security:

Required:

• GRAPHQL_URL - GraphQL endpoint URL
  • Example: https://adp-api.endpoint.com/1234567/v1
• GRAPHQL_AUTH_LOGIN - Authentication login for API access
• GRAPHQL_AUTH_TOKEN - Authentication token for API access

Optional:

• ACC_VARIANT - ACC variant name (adds x-oa-variant: DOMAIN::VARIANT header)
• DEBUG - Enable debug logging (default: false)

Usage Examples

# Standard usage
GRAPHQL_URL=https://api.example.com/1234567/v1 \
GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \
GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \
adpapi-mcp-server

# Local development
GRAPHQL_URL=http://localhost:3000/graphql \
GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \
GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \
adpapi-mcp-server

# With ACC variant for testing
GRAPHQL_URL=https://api.example.com/1234567/v1 \
GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \
GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \
ACC_VARIANT=test_variant \
adpapi-mcp-server

# With debug logging
GRAPHQL_URL=https://api.example.com/1234567/v1 \
GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \
GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \
DEBUG=true \
adpapi-mcp-server

MCP Client Setup

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Using global installation:

{
  "mcpServers": {
    "adpapi-docs": {
      "command": "adpapi-mcp-server",
      "env": {
        "GRAPHQL_URL": "https://adp-api.endpoint.com/1234567/v1",
        "GRAPHQL_AUTH_LOGIN": "YOUR_LOGIN",
        "GRAPHQL_AUTH_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

Using npx (no global installation):

{
  "mcpServers": {
    "adpapi-docs": {
      "command": "npx",
      "args": ["@slawomirjach/adpapi-mcp-server"],
      "env": {
        "GRAPHQL_URL": "https://adp-api.endpoint.com/1234567/v1",
        "GRAPHQL_AUTH_LOGIN": "YOUR_LOGIN",
        "GRAPHQL_AUTH_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

⚠️ Node.js Version Issue with npx:

If you see errors like Cannot find module '@modelcontextprotocol/sdk/server' or Node version: v10.x.x, it means Claude Desktop is using an old Node.js version. This package requires Node.js >= 20.

Solution: Use node command directly instead of npx:

{
  "mcpServers": {
    "adpapi-docs": {
      "command": "/Users/YOUR_USERNAME/.nvm/versions/node/v22.20.0/bin/node",
      "args": [
        "/Users/YOUR_USERNAME/.nvm/versions/node/v22.20.0/bin/npx",
        "@slawomirjach/adpapi-mcp-server"
      ],
      "env": {
        "GRAPHQL_URL": "https://adp-api.endpoint.com/1234567/v1",
        "GRAPHQL_AUTH_LOGIN": "YOUR_LOGIN",
        "GRAPHQL_AUTH_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

To find your Node.js path, run:

which node  # e.g., /Users/YOUR_USERNAME/.nvm/versions/node/v22.20.0/bin/node
which npx   # e.g., /Users/YOUR_USERNAME/.nvm/versions/node/v22.20.0/bin/npx

Local development:

{
  "mcpServers": {
    "adpapi-docs": {
      "command": "adpapi-mcp-server",
      "env": {
        "GRAPHQL_URL": "http://localhost:3000/graphql",
        "GRAPHQL_AUTH_LOGIN": "YOUR_LOGIN",
        "GRAPHQL_AUTH_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

Claude Code

Recommended: One-line command (easiest method):

# Add MCP server with environment variables
claude mcp add --transport stdio adpapi-docs \
  --env GRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \
  --env GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \
  --env GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \
  -- npx @slawomirjach/adpapi-mcp-server

# Using global installation
claude mcp add --transport stdio adpapi-docs \
  --env GRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \
  --env GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \
  --env GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \
  -- adpapi-mcp-server

# With ACC variant
claude mcp add --transport stdio adpapi-docs \
  --env GRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \
  --env GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \
  --env GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \
  --env ACC_VARIANT=test_variant \
  -- npx @slawomirjach/adpapi-mcp-server

Note: The -- separator is important - it distinguishes Claude's flags from the MCP server command.

Verify installation:

# List all MCP servers
claude mcp list

# Check details
claude mcp get adpapi-docs

# Remove if needed
claude mcp remove adpapi-docs

Alternative: Manual configuration - Create .claude/config.json in your project root:

{
  "mcpServers": {
    "adpapi-docs": {
      "command": "npx",
      "args": ["@slawomirjach/adpapi-mcp-server"],
      "env": {
        "GRAPHQL_URL": "https://adp-api.endpoint.com/1234567/v1",
        "GRAPHQL_AUTH_LOGIN": "YOUR_LOGIN",
        "GRAPHQL_AUTH_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

After adding the server, check status in Claude Code with /mcp command.

Cline VS Code Extension

Edit .vscode/settings.json:

{
  "cline.mcpServers": {
    "adpapi-docs": {
      "command": "npx",
      "args": ["@slawomirjach/adpapi-mcp-server"],
      "env": {
        "GRAPHQL_URL": "https://adp-api.endpoint.com/1234567/v1",
        "GRAPHQL_AUTH_LOGIN": "YOUR_LOGIN",
        "GRAPHQL_AUTH_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

Available MCP Tools

search_schema

NEW - Intelligent search in GraphQL schema by partial name. Perfect for AI agents building queries from scratch.

Parameters:

• term (required): Search term (can be partial, e.g., "draft" finds "AdTplDraft", "draft_templates")
• limit (optional): Maximum results (default: 10, max: 10)

Use Cases:

• AI agents building queries: search "campaign" → get full context with example query
• Finding operations by partial name: "lineitem" → finds all lineitem-related operations
• Discovering fields: "status" → finds all fields containing "status"

Scoring Algorithm:

• 900-1000: Exact match
• 700-899: Starts with term
• 500-699: Contains term
• Bonus for: operations > types > fields, higher usage, shorter names

Example:

{
  "term": "draft",
  "limit": 5
}

validate_query

NEW - Validate GraphQL query syntax and detect common ADP API mistakes.

Parameters:

• query (required): GraphQL query to validate
• variables (optional): Query variables for validation

Detects:

• Inline JSON parameters (should use variables)
• Uppercase sort directions (must be lowercase)
• Incorrect Connection structure
• Syntax errors

get_practical_guides

NEW - Get practical user guides and real-world workflow documentation for ADP API.

Parameters:

• topic (optional): Specific topic to retrieve. Leave empty to get the full guide.

Available Topics:

• authentication / auth - API authentication and getting started
• campaign / campaigns / advertising - Creating advertising campaigns (Deal → Line Item → Creative)
• audience / segments - Managing audience segments
• reporting / reports - Generating reports and report definitions
• statistics / stats - Real-time statistics (non-billing)
• custom_fields / customfields - Custom fields and freeform values
• reservation / reservations / crm / oms - Creating reservations (CRM/OMS integration)
• dashboard / dashboards - Dashboard URL generation
• best_practices / bestpractices - Best practices and tips
• overview - API overview

Features:

• Step-by-step workflows for common tasks
• Complete GraphQL examples with variables
• Practical explanations of API concepts
• Best practices and gotchas
• Real-world usage patterns

Example:

{
  "tool": "get_practical_guides",
  "params": {
    "topic": "campaign"
  }
}

Use Cases:

• "How do I create an advertising campaign?"
• "What are the steps for managing audience segments?"
• "Show me how to generate a report"
• "What are best practices for using this API?"

get_common_mistakes

NEW - Get list of most common API usage mistakes with corrections.

Returns:

• 10+ common mistakes grouped by category
• Wrong/correct examples for each
• Severity levels (critical, high, medium)
• Quick tips summary

Critical Mistakes:

• Sort uppercase (DESC/ASC vs desc/asc)
• Inline JSON (not using variables)
• Connection structure (using "node" wrapper)
• Missing root field (dream_adserver)

get_schema

Retrieve GraphQL schema documentation for a type or operation from ADP API.

Parameters:

• name (required): Type name (e.g., "DASDeal") or operation name (e.g., "deals")
• includeRelated (optional): Include related operations (default: false)

Enhanced Features:

• For operations with JSON parameters (filter, sort), returns jsonFormat with:
  • Operator documentation for filters (=, !=, >, <, >=, <=, in, like)
  • Format examples and allowed values
  • Inline hints pointing to get_common_patterns
• For Connection return types, returns connectionMetadata with:
  • Edge structure (direct vs node-wrapped)
  • What type edges returns
  • Pagination fields available
  • Usage examples

Example:

{
  "tool": "get_schema",
  "params": {
    "name": "lineitems",
    "includeRelated": false
  }
}

Example Response (partial):

{
  "name": "lineitems",
  "type": "query",
  "arguments": [
    {
      "name": "filter",
      "type": "JSON",
      "jsonFormat": {
        "operators": ["=", "!=", ">", "<", ">=", "<=", "in", "like"],
        "example": "{\"lineitem_type\": {\"=\": \"MAILING\"}}"
      },
      "hint": "💡 Use get_common_patterns to see filtering examples"
    }
  ],
  "returnType": "DASLineitemConnection",
  "connectionMetadata": {
    "edgesStructure": "direct",
    "note": "This API uses custom Connection structure WITHOUT node wrapper",
    "edgesReturns": "DASLineitem",
    "example": "edges { id name } total_count"
  }
}

get_examples

Get executable GraphQL query examples with variables.

Parameters:

• operationName (required): Operation name (e.g., "deals", "set_lineitem")
• includeRealWorld (optional): Include real-world examples from codebase (default: true)

Enhanced Features:

• When no real-world examples exist, automatically generates examples from schema:
  • Simple: Basic query with common fields (limit: 10)
  • Medium: Query with filter using operator-based syntax
  • Advanced: Full query with filter, sort, and pagination
• All generated examples are executable and follow API conventions
• Handles Connection types correctly (no 'node' wrapper)

Example:

{
  "tool": "get_examples",
  "params": {
    "operationName": "lineitems"
  }
}

Example Response:

{
  "note": "No production examples found. Generated examples based on schema:",
  "examplesFromCode": [],
  "generatedExamples": [
    {
      "name": "Basic query - first 10 items",
      "complexity": "simple",
      "description": "Get first 10 lineitems with common fields",
      "query": "query GetLineitems {\n  dream_adserver {\n    lineitems(limit: 10) {\n      edges {\n        lineitem_id\n        lineitem_name\n      }\n      total_count\n    }\n  }\n}",
      "variables": {},
      "source": "generated"
    },
    {
      "name": "Filtered query - with type filter",
      "complexity": "medium",
      "query": "...",
      "source": "generated"
    },
    {
      "name": "Full query - with filter and sort",
      "complexity": "advanced",
      "query": "...",
      "source": "generated"
    }
  ]
}

get_common_patterns

Get comprehensive documentation of common API usage patterns.

Parameters: None

Returns:

• Filtering: Operator-based filter syntax with 8 operators
  • Equality, inequality, comparisons (>, <, >=, <=)
  • Array membership (in)
  • Pattern matching (like with SQL wildcards)
  • 5 real-world examples
  • Best practice tips
• Sorting: Field-based sort syntax
  • ASC/DESC directions
  • Multi-field sorting
  • Examples and tips
• Connections: Custom Connection structure
  • Standard vs ADP API structure
  • Common mistakes and corrections
  • Working examples
• Pagination: limit/offset patterns
  • Parameter documentation
  • Page calculation formula
  • Multi-page examples
• Complete Example: Full working query combining all patterns

Example:

{
  "tool": "get_common_patterns",
  "params": {}
}

Use Cases:

• Learning API conventions before writing first query
• Reference for filter/sort syntax
• Understanding Connection type structure
• Debugging query issues

list_domains

List all API domains with statistics and top operations.

Parameters: None

Enhanced Features:

• Lists domains with query/example counts
• For each domain, shows:
  • Top 5 operations by usage frequency
  • Whether examples exist for each operation
  • Operation descriptions
• Common patterns summary for the domain:
  • Filtering approach
  • Sorting approach
  • Connection structure
  • Pagination method

Example:

{
  "tool": "list_domains",
  "params": {}
}

Example Response (partial):

{
  "domain": "Core",
  "queryCount": 9,
  "exampleCount": 353,
  "topOperations": [
    {
      "name": "lineitems",
      "type": "query",
      "hasExamples": true,
      "usageFrequency": 42,
      "description": "Fetch line items with filtering and sorting"
    }
  ],
  "commonPatterns": {
    "filtering": "Uses operator-based JSON filters: {field: {'=': value}}",
    "sorting": "Uses field-based JSON: {field: 'ASC'|'DESC'}",
    "connections": "Custom structure without 'node' wrapper",
    "pagination": "Use limit and offset parameters"
  }
}

Usage Examples

Learning the API from Scratch

Step 1: Get overview of common patterns

"What are the common patterns for filtering and sorting in ADP API?"

Server calls get_common_patterns → Returns comprehensive pattern documentation

Step 2: Explore available domains

"What API domains are available?"

Server calls list_domains → Returns domains with top operations

Step 3: Get examples for specific operation

"Show me how to query lineitems"

Server calls get_examples → Returns 3 auto-generated examples (simple, medium, advanced)

Result: You can write your first working query in 1-2 iterations instead of 7+

Query for Type Documentation

Ask in your MCP client:

"What fields are available on the DASDeal type?"

The server will call get_schema and return complete type documentation from ADP API.

For operations with filters:

"How do I filter lineitems?"

Server calls get_schema for "lineitems" → Returns jsonFormat with operator docs and hint to use get_common_patterns

Get Query Examples

Ask in your MCP client:

"Show me examples of how to fetch advertisers from ADP API"

The server will call get_examples and return executable queries with variables.

If no real examples exist, you'll get auto-generated examples at 3 complexity levels.

Understanding Filters and Sorting

Ask in your MCP client:

"How do I use filters in ADP API queries?"

Server calls get_common_patterns → Returns complete filter documentation with operators and examples

"Show me how to sort results"

Server calls get_common_patterns → Returns sort syntax and multi-field examples

Working with Connections

Ask in your MCP client:

"How do Connection types work in ADP API?"

Server calls get_common_patterns → Returns Connection structure docs, highlighting custom structure without 'node' wrapper

Or check schema for specific operation:

"What does the lineitems query return?"

Server calls get_schema → Returns connectionMetadata explaining the structure

Browse Domains

Ask in your MCP client:

"What API domains are available in ADP API?"

The server will call list_domains and return domain statistics with top operations and pattern summaries.

Architecture

MCP Client (Claude Desktop / Cline / other)
    ↓ stdio (JSON-RPC)
MCP Server (@slawomirjach/adpapi-mcp-server)
    ↓ HTTP introspection
ADP API GraphQL endpoint
    ↓ optional: file system
.graphql example files (if provided)

How It Works

1. Initialization: Server connects to ADP API GraphQL endpoint via introspection query
2. Schema Loading: Builds searchable index of types, operations, and fields
3. Auto-Generation: Creates examples for operations from schema
4. MCP Protocol: Exposes tools via Model Context Protocol for AI assistants

File Structure

adpapi-mcp-server/
├── index.js                     # MCP server entry point
├── logger.js                   # Structured JSON logger
├── schema-loader.js            # GraphQL schema introspection
├── example-generator.js        # Auto-generate examples from schema
├── mcp-tools.js               # MCP tool definitions and handlers
├── common-patterns.js         # Common API pattern documentation
├── filter-docs.js             # Filter operator documentation
└── utils/
    ├── frequency-analyzer.js    # Usage frequency analysis
    └── deprecation-detector.js  # Deprecation detection

Development

Local Development

# Clone and install dependencies
git clone <your-fork>
cd adpapi-mcp-server
npm install

# Run with your GraphQL endpoint (with authentication via env vars)
GRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \
GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \
GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \
npm start

# Or use dev script for local API
GRAPHQL_URL=http://localhost:3000/graphql \
GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \
GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \
npm run dev

Debug Logging

GRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \
GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \
GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \
DEBUG=true \
adpapi-mcp-server

Adding New Tools

1. Implement tool handler in mcp-tools.js
2. Add tool definition to getToolDefinitions()
3. Register handler in index.js CallToolRequestSchema handler
4. Update README.md with tool documentation

Performance

• Startup Time: ~3-5 seconds (schema + examples loading)
• Response Time: <2 seconds for 95% of requests
• Memory Usage: ~50MB peak
• Concurrency: Handles 10+ concurrent requests

Troubleshooting

Server Not Starting

Check logs for errors:

tail -f ~/.mcp/logs/adpapi-docs.log

Verify ADP API is running:

curl http://localhost:3000/graphql

Schema Not Loading

Test introspection query manually:

query {
  __schema {
    types {
      name
    }
  }
}

Examples Not Found

Note: The server auto-generates examples from the GraphQL schema, so you should always get usable examples for any GraphQL operation.

Queries Not Working

Common issues:

1. Using 'node' wrapper in Connection queries

# ❌ WRONG - Standard GraphQL Connection
query {
  dream_adserver {
    lineitems {
      edges {
        node {  # This doesn't exist in ADP API
          lineitem_id
        }
      }
    }
  }
}

# ✅ CORRECT - ADP API custom Connection
query {
  dream_adserver {
    lineitems {
      edges {  # Direct access to items
        lineitem_id
      }
      total_count
    }
  }
}

2. Wrong filter format

# ❌ WRONG - Direct value
filter: {
  lineitem_type: "MAILING"
}

# ✅ CORRECT - Operator-based
filter: {
  lineitem_type: {"=": "MAILING"}
}

3. Wrong sort format

# ❌ WRONG - Object with field/order
sort: {
  field: "lineitem_id",
  order: "DESC"
}

# ✅ CORRECT - Field as key, direction as value
sort: {
  lineitem_id: "DESC"
}

Solution: Use get_common_patterns tool to see correct formats for all these patterns.

Node.js Version Requirement

Requires Node.js >= 20

node --version  # Should be v20.0.0 or higher

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

License

MIT

Resources

• MCP Specification
• npm Package
• GitHub Issues

Support

For issues and questions:

• Open an issue on GitHub
• Check existing issues for similar problems
• Review the troubleshooting section above