Babel Licensing MCP Server

The Babel Licensing MCP Server is a Python-based Model Context Protocol  (MCP) server that exposes all Babel Licensing API functions as tools. This enables AI assistants like Claude to interact directly with your Babel Licensing system for license management, customer operations, product management, and more.

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external systems and data sources. MCP servers act as bridges between AI models and your business systems, allowing natural language interactions with APIs, databases, and tools.

Features

• Complete API Coverage: Exposes all 90+ Babel Licensing API endpoints as MCP tools
• Type-Safe Configuration: Pydantic-based configuration with automatic validation
• Authentication Support: Supports both API Key and Bearer Token authentication
• Daily Log Rotation: Automatic logging to logs/ directory with daily file rotation
• Comprehensive Toolset: Includes tools for:
  • Authentication and user management
  • License operations (activate, deactivate, validate, request, release)
  • Customer and contact management
  • Product and order management
  • License templates and tokens
  • Webhooks and event management
  • Reports and logging
  • Email notifications
  • System settings and configuration

Requirements

• Python 3.10 or higher
• Babel Licensing API access (base URL and credentials)
• An MCP-compatible client (e.g., Claude Desktop)

Installation

Quick Start

macOS / Linux

1. Extract the archive and navigate to the directory:

unzip babel-licensing-mcp-*.zip
cd babel-licensing-mcp-*

2. Run the setup script:

chmod +x setup.sh
./setup.sh

3. Configure your environment:

# Edit .env file with your Babel Licensing API credentials
nano .env

Windows

1. Extract the ZIP archive and navigate to the directory in PowerShell

2. Enable PowerShell script execution (if needed):

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

3. Run the setup script:

.\setup.ps1

4. Configure your environment:

# Edit .env file with your Babel Licensing API credentials
notepad .env

Manual Installation

1. Create a virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies:

pip install -r requirements.txt

3. Configure environment variables:

cp .env.example .env
# Edit .env with your actual credentials

Configuration

The server requires the following environment variables (configured in .env):

# Babel Licensing API Base URL
BABEL_API_BASE_URL=https://your-babel-licensing-server.com
 
# Authentication - Use ONE of the following:
# Option 1: API Key
BABEL_API_KEY=your-api-key-here
 
# Option 2: Bearer Token
# BABEL_BEARER_TOKEN=your-bearer-token-here
 
# Optional Configuration
# BABEL_VERIFY_SSL=true           # Set to false for self-signed certificates
# BABEL_TIMEOUT=30                # Request timeout in seconds
# BABEL_CONTENT_TYPE=application/json  # Content type: application/json or application/toon
# DEBUG=false                      # Enable debug logging

Content Type Configuration

The server supports two content types for API requests:

• application/json (default): Standard JSON format
• application/toon: TOON format for specialized use cases

To use TOON format, set the BABEL_CONTENT_TYPE environment variable:

BABEL_CONTENT_TYPE=application/toon

The client will automatically set the appropriate Content-Type and Accept headers for all API requests.

Usage

Running the MCP Server

Option 1: Using the installed command

babel-licensing-mcp

Option 2: Direct execution

python src/server.py

Configuring with AI Clients

The Babel Licensing MCP Server can be used with any MCP-compatible AI client, including Claude Desktop and Claude Code.

Configuring with Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Recommended Configuration (Direct Path)

{
  "mcpServers": {
    "babel-licensing": {
      "command": "/absolute/path/to/babel-licensing-mcp/venv/bin/python",
      "args": [
        "/absolute/path/to/babel-licensing-mcp/src/server.py"
      ],
      "env": {
        "BABEL_API_BASE_URL": "https://your-babel-server.com",
        "BABEL_API_KEY": "your-api-key-here"
      }
    }
  }
}

Example with actual paths (macOS):

{
  "mcpServers": {
    "babel-licensing": {
      "command": "/Users/username/Projects/babel-licensing-mcp/venv/bin/python",
      "args": [
        "/Users/username/Projects/babel-licensing-mcp/src/server.py"
      ],
      "env": {
        "BABEL_API_BASE_URL": "https://api.babel-licensing.com",
        "BABEL_API_KEY": "abc123def456"
      }
    }
  }
}

Example with actual paths (Windows):

{
  "mcpServers": {
    "babel-licensing": {
      "command": "C:\\Users\\username\\Projects\\babel-licensing-mcp\\venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\username\\Projects\\babel-licensing-mcp\\src\\server.py"
      ],
      "env": {
        "BABEL_API_BASE_URL": "https://api.babel-licensing.com",
        "BABEL_API_KEY": "abc123def456"
      }
    }
  }
}

Note: Replace /absolute/path/to/ with the actual path to your project directory. You can find it by running pwd (macOS/Linux) or cd (Windows) in the project folder.

Alternative: Using .env file

Instead of specifying environment variables in the Claude Desktop config, you can create a .env file in the project root:

# Copy the example file
cp .env.example .env
 
# Edit with your credentials
BABEL_API_BASE_URL=https://your-babel-server.com
BABEL_API_KEY=your-api-key-here

Then use a simpler Claude Desktop configuration:

{
  "mcpServers": {
    "babel-licensing": {
      "command": "/absolute/path/to/babel-licensing-mcp/venv/bin/python",
      "args": [
        "/absolute/path/to/babel-licensing-mcp/src/server.py"
      ]
    }
  }
}

After Configuration:

1. Completely quit and restart Claude Desktop
2. Start a new conversation
3. Look for the 🔨 tools icon indicating MCP servers are connected
4. Ask Claude: “What Babel Licensing tools do you have access to?”

Configuring with Claude Code

Claude Code is a VS Code extension that provides AI assistance directly in your development environment. To use the Babel Licensing MCP Server with Claude Code:

Step 1: Install Claude Code

Install the Claude Code extension from the VS Code marketplace:

1. Open VS Code
2. Go to Extensions (Cmd+Shift+X on macOS, Ctrl+Shift+X on Windows/Linux)
3. Search for “Claude Code”
4. Click Install

Step 2: Add MCP Server to Settings

Open your VS Code settings and add the MCP server configuration:

Option A: Workspace Settings (recommended for project-specific usage)

Create or edit .vscode/settings.json in your workspace:

{
  "claude.mcpServers": {
    "babel-licensing": {
      "command": "/absolute/path/to/babel-licensing-mcp/venv/bin/python",
      "args": [
        "/absolute/path/to/babel-licensing-mcp/src/server.py"
      ],
      "env": {
        "BABEL_API_BASE_URL": "https://licensing.example.com",
        "BABEL_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option B: User Settings (for global access across all workspaces)

1. Open Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux)
2. Type “Preferences: Open User Settings (JSON)”
3. Add the claude.mcpServers configuration:

{
  "claude.mcpServers": {
    "babel-licensing": {
      "command": "/Users/username/Projects/babel-licensing-mcp/venv/bin/python",
      "args": [
        "/Users/username/Projects/babel-licensing-mcp/src/server.py"
      ],
      "env": {
        "BABEL_API_BASE_URL": "https://licensing.example.com",
        "BABEL_API_KEY": "your-api-key-here"
      }
    }
  }
}

Step 3: Using Environment Variables

You can reference environment variables in your configuration:

{
  "claude.mcpServers": {
    "babel-licensing": {
      "command": "/path/to/babel-licensing-mcp/venv/bin/python",
      "args": ["/path/to/babel-licensing-mcp/src/server.py"],
      "env": {
        "BABEL_API_BASE_URL": "${env:BABEL_URL}",
        "BABEL_API_KEY": "${env:BABEL_KEY}"
      }
    }
  }
}

Then set the environment variables in your shell before starting VS Code:

# macOS/Linux
export BABEL_URL="https://licensing.example.com"
export BABEL_KEY="your-api-key-here"
code .
 
# Windows PowerShell
$env:BABEL_URL = "https://licensing.example.com"
$env:BABEL_KEY = "your-api-key-here"
code .

Step 4: Using .env File (simplest approach)

Configure the .env file in the MCP server directory with your credentials, then use a minimal configuration:

{
  "claude.mcpServers": {
    "babel-licensing": {
      "command": "/path/to/babel-licensing-mcp/venv/bin/python",
      "args": ["/path/to/babel-licensing-mcp/src/server.py"]
    }
  }
}

The server will automatically load settings from the .env file.

Step 5: Platform-Specific Path Examples

macOS:

{
  "claude.mcpServers": {
    "babel-licensing": {
      "command": "/Users/username/Projects/babel-licensing-mcp/venv/bin/python",
      "args": [
        "/Users/username/Projects/babel-licensing-mcp/src/server.py"
      ]
    }
  }
}

Windows:

{
  "claude.mcpServers": {
    "babel-licensing": {
      "command": "C:\\Users\\username\\Projects\\babel-licensing-mcp\\venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\username\\Projects\\babel-licensing-mcp\\src\\server.py"
      ]
    }
  }
}

Linux:

{
  "claude.mcpServers": {
    "babel-licensing": {
      "command": "/home/username/projects/babel-licensing-mcp/venv/bin/python",
      "args": [
        "/home/username/projects/babel-licensing-mcp/src/server.py"
      ]
    }
  }
}

Step 6: Using Relative Paths

For workspace-specific configurations, you can use VS Code variables:

{
  "claude.mcpServers": {
    "babel-licensing": {
      "command": "${workspaceFolder}/../babel-licensing-mcp/venv/bin/python",
      "args": [
        "${workspaceFolder}/../babel-licensing-mcp/src/server.py"
      ],
      "cwd": "${workspaceFolder}/../babel-licensing-mcp"
    }
  }
}

This is useful when the MCP server is in a sibling directory to your workspace.

Step 7: Verify Installation

After configuring, reload VS Code to activate the MCP server:

1. Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
2. Type “Developer: Reload Window”
3. Press Enter

To verify the server is working:

1. Open the Claude panel in VS Code
2. Start a new conversation
3. Ask: “What Babel Licensing capabilities do you have?”
4. Claude should list all 86 available tools

Claude Code Usage Tips:

1. Context-Aware Requests: Claude Code can see your current file and workspace, so you can ask:

   • “Based on this code, create a license for this customer”
   • “Generate a license activation call for the product in this file”

2. Code Generation: Ask Claude to generate code that uses the Babel Licensing API:

   • “Write a C# method to activate a license using these parameters”
   • “Create a Python script to query all active licenses”

3. Inline Assistance: Select code and ask Claude to:

   • “Check if this license key is valid”
   • “Find the customer associated with this user key”

4. Multi-File Operations: Claude can help coordinate licensing across multiple files:

   • “Update license keys in all configuration files”
   • “Find all hardcoded license keys in this project”

Troubleshooting Claude Code:

If the MCP server doesn’t connect:

1. Check Extension Status: Ensure Claude Code extension is activated
2. Verify Python Path: Confirm the virtual environment path is correct
3. Check Logs: View Claude Code output in VS Code Output panel
4. Reload Window: Use “Developer: Reload Window” after config changes
5. Check Permissions: Ensure the Python executable has execute permissions

Multiple Environment Setup:

You can configure different Babel Licensing environments:

{
  "claude.mcpServers": {
    "babel-licensing-prod": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/src/server.py"],
      "env": {
        "BABEL_API_BASE_URL": "https://licensing.production.com",
        "BABEL_API_KEY": "${env:BABEL_PROD_KEY}"
      }
    },
    "babel-licensing-dev": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/src/server.py"],
      "env": {
        "BABEL_API_BASE_URL": "https://licensing.dev.com",
        "BABEL_API_KEY": "${env:BABEL_DEV_KEY}"
      }
    }
  }
}

This allows you to switch between production and development environments when working with Claude.

Logging

The server automatically logs all operations to daily log files in the logs/ directory:

• Location: logs/babel_licensing_YYYYMMDD.log
• Format: Timestamped logs with level and module information
• Rotation: Automatically creates a new file each day
• Output: Logs are written to both file and console

Example log file: logs/babel_licensing_20251111.log

2025-11-11 10:30:15 - server - INFO - MCP server starting...
2025-11-11 10:30:16 - server - INFO - Babel Licensing client initialized
2025-11-11 10:31:22 - server - INFO - Tool called: babel_get_customers

Available Tools

The server exposes 86 tools organized into the following categories:

Note: Authentication is handled automatically via API Key or Bearer Token configured in environment variables. Interactive login tools are not required.

Licensing Operations (7 tools)

• babel_activate_license - Activate a license
• babel_deactivate_license - Deactivate a license
• babel_request_license - Request a license
• babel_release_license - Release a license
• babel_license_heartbeat - Send license heartbeat
• babel_validate_license - Validate a license
• babel_get_license_info - Get license information

Management

API Keys (4 tools)

• babel_get_api_keys - List API keys
• babel_insert_api_key - Create new API key
• babel_update_api_key - Update API key
• babel_delete_api_key - Delete API key

Users (7 tools)

• babel_get_users - List users
• babel_insert_user - Create user
• babel_update_user - Update user
• babel_delete_user - Delete user
• babel_get_user_roles - Get user roles
• babel_add_user_to_roles - Add user to roles
• babel_remove_user_from_roles - Remove user from roles

Customers (7 tools)

• babel_get_customers - List customers
• babel_insert_customer - Create customer
• babel_update_customer - Update customer
• babel_delete_customer - Delete customer
• babel_get_customer_contacts - Get customer contacts
• babel_get_customer_orders - Get customer orders
• babel_get_customer_licenses - Get customer licenses

Products (15 tools)

• Product management (get, insert, update, delete)
• Product releases management
• Release assemblies management
• License templates for releases

Orders (9 tools)

• Order management (get, insert, update, delete)
• Order products management
• Order licenses retrieval

Licenses (9 tools)

• License management (get, insert, update, delete)
• License tokens management
• License traces
• License templates

Webhooks (9 tools)

• Webhook subscriptions management
• Event types retrieval
• Webhook testing
• Event management

Additional Management Tools

• Assemblies (4 tools)
• Contacts (4 tools)
• Resources (4 tools)
• Reports (3 tools)
• Logging (3 tools)
• Settings (2 tools)
• Email (2 tools)
• Server Info (1 tool)

Working with the API

Data Format for Insert/Update Operations

When using tools that create or update resources (tools starting with babel_insert_ or babel_update_), the client automatically wraps your data in the appropriate request format required by the Babel Licensing API.

You only need to provide the raw data - the wrapping is handled automatically.

Examples

Creating a new customer:

// You provide:
{
  "customer_data": {
    "name": "Acme Corporation",
    "email": "contact@acme.com"
  }
}
 
// The client automatically wraps it as:
{
  "customer": {
    "name": "Acme Corporation",
    "email": "contact@acme.com"
  }
}

Creating a new user:

// You provide:
{
  "user_data": {
    "userName": "johndoe",
    "email": "john@example.com",
    "password": "SecureP@ssw0rd"
  }
}
 
// The client automatically wraps it as:
{
  "user": {
    "userName": "johndoe",
    "email": "john@example.com"
  },
  "password": "SecureP@ssw0rd"
}

Updating a license:

// You provide:
{
  "license_data": {
    "id": 123,
    "revoked": false,
    "description": "Updated description"
  }
}
 
// The client automatically wraps it as:
{
  "license": {
    "id": 123,
    "revoked": false,
    "description": "Updated description"
  }
}

Query Parameters

Many GET endpoints support the following query parameters:

• select - Comma-separated list of field names to include in response
• filter - Filtering criteria using .NET syntax (see Filter Syntax below)
• include - Comma-separated list of related objects to include (see Include Parameter below)
• sort - Field name with optional ‘asc’ or ‘desc’
• take - Pagination limit (page size)
• skip - Pagination offset

Include Parameter

The include parameter allows you to fetch related objects in a single request.

IMPORTANT Rules:

1. Use PascalCase names (capitalized): Customer, Order, Product (NOT customer, order, product)
2. MUST add included objects to select - include them in both parameters
3. Multiple objects: separate with comma without spaces

Examples:

// Correct - Get licenses with customer and order objects
{
  "params": {
    "select": "id,licenseId,licenseType,createdAt,customerId,orderId,Customer,Order",  //  Include Customer,Order here
    "include": "Customer,Order"  //  PascalCase, no spaces
  }
}
 
// Wrong - lowercase names
{
  "params": {
    "select": "id,licenseId,customer,order",  // L Lowercase
    "include": "customer,order"  // L Will fail
  }
}
 
// Wrong - missing from select
{
  "params": {
    "select": "id,licenseId,licenseType",  // L Missing Customer,Order
    "include": "Customer,Order"  // Objects won't be returned!
  }
}

Available Include Options:

• babel_get_licenses: Product, Order, Customer, Template, Licensee
• babel_get_customers: Contacts, Orders, Licenses
• babel_get_orders: Customer, Reseller, Products, Licenses
• babel_get_products: Releases, Orders
• babel_get_users: Roles, Settings, Customer
• babel_get_api_keys: Owner
• babel_get_all_license_tokens: License, NodeLockedLicense
• babel_get_license_templates: Product

Filter Syntax

The API uses .NET filter syntax, NOT OData standard.

Comparison Operators:

Logical Operators:

String Functions:

Complex Filter Examples:

# Active licenses of Ultimate type created after Nov 11
revoked == false && licenseType.Contains("Ultimate") && createdAt >= "2025-11-11T00:00:00"

# Exclude Enterprise licenses
!licenseType.Contains("Enterprise")

# User keys starting with ABC or XYZ
userKey.StartsWith("ABC") || userKey.StartsWith("XYZ")

# Expired licenses excluding trial
expireDate < "2025-01-01T00:00:00" && !licenseType.Contains("Trial")

IMPORTANT: Do NOT use OData syntax (eq, ne, gt, lt, and, or). These will not work.

Sort Parameter:

The sort parameter accepts:

• Field name with direction: createdAt desc (descending)
• Field name with direction: createdAt asc (ascending)
• Field name only: createdAt (defaults to ascending)

Complete Example:

{
  "params": {
    "filter": "revoked == false && licenseType.Contains(\"Ultimate\") && expireDate >= \"2025-01-01T00:00:00\"",
    "select": "id,licenseId,userKey,expireDate,licenseType",
    "take": 10,
    "skip": 0,
    "sort": "createdAt desc"
  }
}

Examples

Activating a License

Ask Claude:

“Activate a license with user key ABC-123-DEF, product code PROD001, and hardware ID HW-12345”

Claude will use the babel_activate_license tool:

{
  "tool": "babel_activate_license",
  "arguments": {
    "license_data": {
      "userKey": "ABC-123-DEF",
      "productCode": "PROD001",
      "hardwareId": "HW-12345"
    }
  }
}

Getting Customers

Ask Claude:

“Show me the first 10 reseller customers, sorted by company name”

Claude will use the babel_get_customers tool:

{
  "tool": "babel_get_customers",
  "arguments": {
    "params": {
      "filter": "isReseller == true",
      "take": 10,
      "sort": "company asc"
    }
  }
}

Creating a Webhook Subscription

Ask Claude:

“Create a webhook subscription for license activation and deactivation events pointing to https://example.com/webhook ”

Claude will use the babel_create_webhook_subscription tool:

{
  "tool": "babel_create_webhook_subscription",
  "arguments": {
    "subscription_data": {
      "url": "https://example.com/webhook",
      "events": ["license.activated", "license.deactivated"],
      "isActive": true
    }
  }
}

Complex Query Example

Ask Claude:

“Show me all Ultimate licenses created after November 11, 2025 that are not revoked, including customer and order details, sorted by creation date”

Claude will construct a query like:

{
  "tool": "babel_get_licenses",
  "arguments": {
    "params": {
      "filter": "revoked == false && licenseType.Contains(\"Ultimate\") && createdAt >= \"2025-11-11T00:00:00\"",
      "select": "id,licenseId,userKey,expireDate,licenseType,createdAt,Customer,Order",
      "include": "Customer,Order",
      "sort": "createdAt desc"
    }
  }
}

Troubleshooting

Connection Issues

1. Verify your BABEL_API_BASE_URL is correct
2. Ensure your API key or bearer token is valid
3. Check network connectivity to the Babel Licensing server
4. Review server logs in the logs/ directory for detailed error messages

SSL Certificate Issues

If you encounter SSL certificate verification errors (especially with self-signed certificates):

1. Set BABEL_VERIFY_SSL=false in your .env file or environment configuration
2. For Claude Desktop, add it to the env section:

   {
     "mcpServers": {
       "babel-licensing": {
         "command": "/path/to/venv/bin/python",
         "args": ["/path/to/src/server.py"],
         "env": {
           "BABEL_API_BASE_URL": "https://your-server.com",
           "BABEL_API_KEY": "your-key",
           "BABEL_VERIFY_SSL": "false"
         }
       }
     }
   }

Security Note: Only disable SSL verification for trusted internal servers with self-signed certificates. Never disable it for production systems or public APIs.

Authentication Errors

1. Make sure you’re using only ONE authentication method (API key OR bearer token)
2. Verify your credentials are not expired
3. Check that your API key has the necessary permissions

Tool Execution Errors

1. Check the input schema for the tool you’re using
2. Ensure all required parameters are provided
3. Verify parameter types match the schema
4. Review the API response for specific error messages

Token Saturation with babel_get_logs

The babel_get_logs tool can return very large amounts of data, especially when including the exception and properties fields. This can saturate the available AI tokens in the conversation.

Field Selection Guidelines:

• exception and properties: Can contain very large amounts of data - avoid when requesting many records
• messageTemplate: Not strictly necessary as it only contains the formatting template; the actual informative content is in message
• Recommended fields: id, message, level, timeStamp

Best Practices:

1. Limit the fields in select: Avoid including exception, properties, and messageTemplate unless specifically needed

   # Good - excludes large/unnecessary fields
   {
     "params": {
       "select": "id,message,level,timeStamp",
       "take": 50
     }
   }
    
   # Risky - includes large fields
   {
     "params": {
       "select": "id,message,level,timeStamp,exception,properties",
       "take": 50  # May saturate tokens
     }
   }

2. Use pagination wisely: When including exception or properties, use small take values (10-20 records max)

3. Filter before fetching: Use the filter parameter to reduce the number of records before retrieving them

API Documentation

For detailed information about the Babel Licensing API endpoints, parameters, and responses, refer to the babel-licensing-api.json OpenAPI specification file included in the MCP server package.

Support

For issues or questions, contact: support@babelfor.net

Resources

• Model Context Protocol Documentation 
• Claude Desktop 
• Babel Licensing Documentation
• Babel Licensing API Reference

Version History

• 0.1.0 (Initial Release)
  • Complete implementation of all Babel Licensing API endpoints
  • Support for authentication, licensing operations, and management functions
  • Comprehensive test suite
  • Full documentation