Optimizely MCP Server

A Model Context Protocol (MCP) server for Optimizely CMS, providing AI assistants with comprehensive access to Optimizely's GraphQL API and Content Management API.

Version

Current Version: 2.0.0-beta Status: Beta / Pre-Release

This is an active development version and is not yet a release candidate. Features are subject to change, and additional testing is required before production use.

Features

Core Capabilities

• Discovery-First Architecture: Zero hardcoded assumptions about content types or fields

• Dynamic Schema Introspection: Discovers available content types and fields at runtime

• Unified Content Retrieval: Get any content by URL, key, GUID, or search term in one call

• Visual Builder Support: Full support for Optimizely Visual Builder pages with composition structure

• Content Management: Create and manage content via interactive wizard

• Intelligent Field Mapping: Pattern-based field matching with confidence scoring

• GraphQL & CMA Integration: Direct access to both Graph API (read) and Content Management API (write)

• Smart Caching: Built-in caching for improved performance

• Type Safety: Full TypeScript support with runtime validation

API Support

• Graph API: Fast content retrieval, search, and discovery

• Content Management API: Content creation, updates, and draft access

• Dual Authentication: Supports both Graph (single key, HMAC) and CMA (OAuth2) authentication

Installation

# Clone the repository
git clone https://github.com/your-org/optimizely-mcp-server.git
cd optimizely-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Create a .env file in the project root:

# Server Configuration
SERVER_NAME=optimizely-mcp-server
SERVER_VERSION=1.0.0
TRANSPORT=stdio

# Optimizely Graph Configuration
GRAPH_ENDPOINT=https://cg.optimizely.com/content/v2
GRAPH_AUTH_METHOD=single_key # Options: single_key, hmac, basic, bearer, oidc
GRAPH_SINGLE_KEY=your-single-key
# For HMAC auth:
# GRAPH_APP_KEY=your-app-key
# GRAPH_SECRET_KEY=your-secret-key

# Content Management API Configuration
CMA_BASE_URL=https://api.cms.optimizely.com/preview3
CMA_CLIENT_ID=your-client-id  # Get from Settings > API Keys in CMS
CMA_CLIENT_SECRET=your-client-secret
CMA_GRANT_TYPE=client_credentials
CMA_TOKEN_ENDPOINT=https://api.cms.optimizely.com/oauth/token
CMA_IMPERSONATE_USER=  # Optional: User email to impersonate (see Impersonation section)

# Optional Configuration
CACHE_TTL=300000 # Cache TTL in milliseconds (default: 5 minutes)
LOG_LEVEL=info # Options: debug, info, warn, error
MAX_RETRIES=3
TIMEOUT=30000

Running the Server

Development Mode

# Run with hot reloading
npm run dev

# Run with debug logging
LOG_LEVEL=debug npm run dev

Production Mode

# Build and run
npm run build
npm start

# Or run directly
node dist/index.js

Testing the Server

# Run all unit tests
npm test

# Run tests with coverage
npm run test:coverage

# Type checking
npm run typecheck

# Linting
npm run lint

How MCP Servers Work

MCP servers communicate via stdio (standard input/output), not HTTP ports:

• No port required - The server doesn't listen on any network port

• Process-based - Claude Desktop spawns your server as a child process

• JSON-RPC messages - Communication happens through stdin/stdout pipes

• Secure - No network exposure, runs only when Claude needs it

MCP Client Configuration

Claude Desktop Setup

Step 1: Find your config file

Open the configuration file in a text editor:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

For Windows, you can open it quickly with:

notepad %APPDATA%\Claude\claude_desktop_config.json

Step 2: Add the server configuration

{
  "mcpServers": {
    "optimizely": {
      "command": "node",
      "args": ["%USERPROFILE%\\path\\to\\optimizely-mcp-server\\dist\\index.js"],
      "env": {
        "LOG_LEVEL": "error",
        "GRAPH_ENDPOINT": "https://cg.optimizely.com/content/v2",
        "GRAPH_AUTH_METHOD": "single_key",
        "GRAPH_SINGLE_KEY": "your-key",
        "CMA_BASE_URL": "https://api.cms.optimizely.com/preview3/experimental",
        "CMA_CLIENT_ID": "your-client-id",
        "CMA_CLIENT_SECRET": "your-client-secret",
        "CMA_GRANT_TYPE": "client_credentials",
        "CMA_TOKEN_ENDPOINT": "https://api.cms.optimizely.com/oauth/token",
        "CMA_IMPERSONATE_USER": ""
      }
    }
  }
}

In JSON on Windows, you must use double backslashes (\). If your folder path has spaces, this still works because each argument is a separate JSON string.

• Windows: %USERPROFILE% expands to your home directory (e.g., C:\Users\Alice). If Claude doesn’t expand it automatically, replace it with your actual path (e.g., C:\Users\Alice\path\to\optimizely-mcp-server\dist\index.js). In PowerShell, the equivalent is $env:USERPROFILE, but inside this JSON config you should keep %USERPROFILE% or use the full path.

• macOS/Linux: the equivalent shortcut is ~ or $HOME (e.g., /Users/alice or /home/alice). If ~/$HOME isn’t expanded correctly, replace it with the full path.

Step 3: Restart Claude Desktop

After saving the config file:

1. Completely quit Claude Desktop (not just close the window)

2. Start Claude Desktop again

3. The Optimizely tools should now be available

Step 4: Verify it's working

In a new Claude conversation, try:

• "Can you list the available Optimizely tools?"

• "Use the health-check tool to test the connection"

Troubleshooting

If the server doesn't load:

1. Check the file path is correct and uses proper escaping (\\ for Windows)

2. Ensure you've built the project (npm run build)

3. Verify the dist/index.js file exists

4. Check Claude's logs for errors

Other MCP Clients

For other MCP-compatible clients, use the stdio transport configuration:

{
  "name": "optimizely",
  "transport": {
    "type": "stdio",
    "command": "node",
    "args": ["/path/to/optimizely-mcp-server/dist/index.js"]
  },
  "env": {
    // Environment variables as above
  }
}

Available Tools (14 Total)

🌟 Core Discovery & Retrieval Tools

These tools use the Graph API to dynamically discover your CMS structure and retrieve content without hardcoded assumptions.

1. help - 🚀 START HERE! Get context-aware help and learn the discovery-first workflow

   • Examples: help({}), help({"topic": "workflow"})

2. get - 🎯 UNIFIED TOOL - Get content by ANY identifier in ONE call

   • Replaces the old search → locate → retrieve workflow

   • Auto-discovers fields and returns complete content

   • ✅ Supports Visual Builder pages with full composition structure

   • Examples: get({"identifier": "/"}), get({"identifier": "Article 4"})

3. discover - Find content types and fields dynamically

   • No hardcoded assumptions about your CMS structure

   • Examples: discover({"target": "types"}), discover({"target": "fields", "contentType": "ArticlePage"})

4. analyze - Deep analysis of content type requirements

   • Understand fields, constraints, and defaults

   • Example: analyze({"contentType": "ArticlePage"})

5. search - Intelligent content search with auto-discovery

   • ⚠️ Note: get is usually better for most use cases

   • Example: search({"query": "mcp", "contentTypes": ["ArticlePage"]})

6. locate - Find specific content by ID, key, or path

   • ⚠️ Note: get is usually better for most use cases

   • Example: locate({"identifier": "/news/article-1"})

7. retrieve - Get full content from Content Management API

   • ⚠️ Note: get is usually better (uses faster Graph API)

   • Use only when get suggests it or you need CMA-specific data

   • Example: retrieve({"identifier": "12345"})

🔧 Utility Tools (3)

• health-check - Check API connectivity and server health

• get-config - Get current server configuration (sanitized)

• get-documentation - Get documentation for available tools by category

🔧 Content Management Tools (CMA API)

These tools use the Content Management API for write operations and detailed content access:

1. content_creation_wizard - Interactive content creation with discovery

   • Essential for creating new content

   • Example: content_creation_wizard({"step": "start"})

2. content-test-api - Test CMA connectivity and endpoints

   • Validates authentication and permissions

   • Example: content-test-api({})

Note: The retrieve tool (listed in Core Tools above) also uses CMA for accessing draft content and version history.

⚠️ Deprecated Tools (Being Removed)

These Graph API discovery tools are duplicates of the new discover tool and will be removed in a future version:

• graph-introspection - Use discover instead

• type-discover - Use discover({"target": "types"}) instead

• type-match - Use discover instead

• content_type_analyzer - Use analyze instead

• graph_discover_types - Use discover({"target": "types"}) instead

• graph_discover_fields - Use discover({"target": "fields"}) instead

• graph-query - Use get or search instead

Key Architecture Principles

Discovery-First Design

Unlike traditional integrations that hardcode content types and field names, this MCP server:

• Never hardcodes content types - No assumptions about "ArticlePage", "StandardPage", etc.

• Never hardcodes field mappings - No predefined paths like "SeoSettings.MetaTitle"

• Discovers everything dynamically - Uses introspection to understand your CMS

• Adapts to any CMS configuration - Works with custom content types and fields

Intelligent Field Mapping

The server uses pattern matching and similarity scoring to:

• Map user-friendly field names to actual CMS fields

• Handle nested properties automatically

• Generate appropriate default values based on field types

• Provide confidence scores for mappings

Recommended Workflows

Simple Content Retrieval (Most Common)

1. get({"identifier": "homepage"})  # That's it! One call gets everything.

The get tool automatically:

• Detects identifier type (search term, URL, key, or GUID)

• Finds the content

• Discovers all available fields

• Returns complete content including Visual Builder composition

Advanced Discovery Workflow

1. help({})                                              # Learn the workflow
2. discover({"target": "types"})                         # Find content types
3. discover({"target": "fields", "contentType": "..."}) # Get fields
4. get({"identifier": "..."})                           # Retrieve content

Content Creation Workflow

1. discover({"target": "types"})              # Find available types
2. analyze({"contentType": "ArticlePage"})    # Understand requirements
3. content_creation_wizard({...})             # Create with guidance

Visual Builder Support

The get tool fully supports Optimizely Visual Builder (formerly known as Visual Experience Composer) pages:

Features

• ✅ Automatic Detection - Recognizes Visual Builder pages by interface (_IExperience)

• ✅ Complete Composition Retrieval - Returns full structure in a single call

• ✅ Nested Structure - Handles grids, rows, columns, and components

• ✅ Component Content - Includes inline component data directly in composition

• ✅ Recursive Depth - Supports any level of nesting

Understanding Component Types

Visual Builder components come in two types:

1. Inline Components (Embedded Content)

• Key: null or not present

• Content Location: Stored directly in the composition structure

• Access: Content is already included in the get response

• Example: Text components with content like "Welcome to our site"

{
  "component": {
    "_metadata": {
      "types": ["Text", "_Component"],
      "key": null  // ← NULL = inline
    },
    "Content": "Welcome Text"  // ← Content is here
  }
}

Important: Do NOT try to retrieve inline components separately - the content is already provided!

2. Referenced Components (Separate Content Items)

• Key: Valid GUID (e.g., "f7e7f5c9-1e77-4884-a8fc-a9c9ae56560c")

• Content Location: Stored as separate content items in CMS

• Access: Use get({"identifier": "component-key"}) to retrieve full details

• Example: Shared components like Site Settings, reusable blocks

{
  "component": {
    "_metadata": {
      "types": ["ArticleList", "_Component"],
      "key": "f7e7f5c91e774884a8fca9c9ae56560c"  // ← Has key
    }
    // May include basic fields, use get() for full content
  }
}

Best Practices

When working with Visual Builder pages:

1. First, retrieve the page with get({"identifier": "/"})

2. Inspect the composition structure for components

3. For inline components (null key): Content is already in the response ✅

4. For referenced components (has key): Use get({"identifier": "key"}) to fetch full details

Example Usage

// Get a Visual Builder homepage
get({"identifier": "/"})

// Returns complete structure with inline content:
{
  "content": {
    "_metadata": { ... },
    "composition": {
      "nodes": [
        {
          "key": "grid-id",
          "displayName": "Welcome Section",
          "nodes": [
            {
              "component": {
                "_metadata": {
                  "types": ["Text"],
                  "key": null  // Inline - content included
                },
                "Content": "Welcome to our site"
              }
            },
            {
              "component": {
                "_metadata": {
                  "types": ["ArticleList"],
                  "key": "f7e7f5c9..."  // Referenced - fetch separately
                }
              }
            }
          ]
        }
      ]
    }
  }
}

Known Limitations

• Performance - Large compositions may take longer to retrieve due to nested structure

• Referenced Component Details - Basic metadata only; full content requires separate get() call

• Display Settings - Not included in current implementation (can be added if needed)

Important Notes

Content Indexing Delay

After creating new content using the content_creation_wizard or other creation tools:

• Immediate availability in CMA: Content is immediately available via retrieve tool

• Graph API indexing delay: Content may take 1-5 minutes to appear in Graph API results

• Tool behavior: The get and search tools use Graph API and will return "not found" for newly created content until indexing completes

Best practice: After creating content, wait a few minutes before attempting to retrieve it with get or search. Alternatively, use the retrieve tool which queries the CMA directly and has no indexing delay.

Draft vs Published Content

• Graph API: Only returns published content

• CMA API: Returns both draft and published content

• New content: Created in draft status by default

• To make content searchable via get/search, it must be published first

Development

Project Structure

optimizely-mcp-server/
├── src/
│   ├── index.ts          # Server entry point
│   ├── register.ts       # Tool registration
│   ├── config.ts         # Configuration management
│   ├── clients/          # API clients
│   │   ├── graph-client.ts
│   │   └── cma-client.ts
│   ├── logic/            # Tool implementations
│   │   ├── utility/
│   │   ├── graph/
│   │   └── content/
│   ├── types/            # TypeScript types
│   └── utils/            # Utilities
├── tests/                # Test files
├── dist/                 # Built output
└── package.json

Adding New Tools

1. Create tool implementation in src/logic/

2. Add tool registration in appropriate section

3. Add TypeScript types if needed

4. Write tests in tests/

5. Update documentation

Testing Guidelines

• Unit tests for all tool implementations

• Integration tests for API clients

• Mock external API calls

• Test error scenarios

• Maintain >80% coverage

Testing & Debugging

Unit Tests

Run automated tests with Vitest:

# Run unit tests
npm test

# Run with coverage report
npm run test:coverage

Unit tests are located in /tests/ and cover:

• GraphQL client functionality

• CMA client operations

• Health check features

Integration Testing & Debugging

Test your setup with these npm scripts:

# Check credentials are valid
npm run check:credentials

# Test MCP tools
npm run test:tools

# Test with debug output
npm run test:tools:debug

# Test GraphQL connection
npm run debug:graph

# Validate API key format
npm run validate:key

Troubleshooting

Common Issues

1. Authentication Errors

   • Verify your API credentials in .env

   • For CMA: Create API keys in Settings > API Keys in your Optimizely CMS instance

   • Check token expiration for CMA (tokens expire after 5 minutes)

   • Ensure correct auth method for Graph

2. Connection Issues

   • Verify network connectivity

   • Check firewall settings

   • Confirm API endpoints are accessible

3. Build Errors

   • Run npm install to ensure dependencies

   • Check Node.js version (>=18 required)

   • Clear dist/ and rebuild

4. 403 Forbidden Errors (Content Creation)

   • This typically means insufficient permissions

   • See the Impersonation section below for a solution

   • Verify the user has content creation rights

   • Check the target container allows the content type

Debug Mode

Enable debug logging for troubleshooting:

LOG_LEVEL=debug npm start

Health Check

Test server connectivity:

# Using the built tool
echo '{"method": "tools/call", "params": {"name": "health_check"}}' | node dist/index.js

User Impersonation

If you encounter 403 Forbidden errors when creating content, you can use user impersonation to execute API calls as a specific user who has the necessary permissions.

When to Use Impersonation

Use impersonation when:

• The API client lacks content creation permissions

• You need to test with different user permission levels

• You want actions attributed to a specific user

Setup Instructions

1. Enable Impersonation in Optimizely CMS:

   • Log into Optimizely CMS as an administrator

   • Navigate to Settings > API Clients

   • Find your API client

   • Enable the "Allow impersonation" option

   • Save the changes

2. Configure the MCP Server:

   # In your .env file
   CMA_IMPERSONATE_USER=user@example.com

3. Update Claude Desktop Config (if using environment variables):

   {
     "mcpServers": {
       "optimizely": {
         "env": {
           "CMA_IMPERSONATE_USER": "user@example.com",
           // ... other settings
         }
       }
     }
   }

How It Works

When impersonation is configured:

• Authentication requests use JSON format with act_as field

• All content operations execute as the impersonated user

• Created content shows the impersonated user as the author

Testing Impersonation

Test that impersonation is working:

# Run the impersonation test script
node scripts/test-impersonation-final.js

This will create test content and show which user created it.

Security Best Practices

• Only enable impersonation when necessary

• Use accounts with minimal required permissions

• Regularly review API client permissions

• Monitor API usage logs for unusual activity

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests

5. Run npm test and npm run typecheck

6. Submit a pull request

License

MIT