Headlesshost MCP Server

A Model Context Protocol (MCP) server that provides complete communication with the Headlesshost platform API. This server enables AI assistants to manage content sites, staging sites, pages, sections, audiences, users, and file uploads through the Headlesshost platform.

Built with @modelcontextprotocol/sdk v1.26 and includes tool annotations, structured logging, and Zod input validation.

Demo

https://www.youtube.com/watch?v=xGGwcrI7gSo&feature=youtu.be

Installation

1. Clone this repository

2. Install dependencies:

   npm install
   

3. Build the server:

   npm run build
   

Configuration

The server requires a Headlesshost API key set via the HEADLESSHOST_API_KEY environment variable.

Usage

With Claude Desktop

Add this configuration to your Claude Desktop config file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Local development

{
  "mcpServers": {
    "headlesshost-cms": {
      "command": "node",
      "args": ["/path/to/kapiti.mcp/build/index.js"],
      "env": {
        "HEADLESSHOST_API_KEY": "your-auth-token"
      }
    }
  }
}

Via npx

{
  "mcpServers": {
    "headlesshost-cms": {
      "command": "npx",
      "args": ["headlesshost-mcp-server@latest"],
      "env": {
        "HEADLESSHOST_API_KEY": "your-auth-token"
      }
    }
  }
}

With Claude Code

Add to your .claude/settings.json:

{
  "mcpServers": {
    "headlesshost-cms": {
      "command": "node",
      "args": ["/path/to/kapiti.mcp/build/index.js"],
      "env": {
        "HEADLESSHOST_API_KEY": "your-auth-token"
      }
    }
  }
}

With Other MCP Clients

This server is compatible with any MCP client including VS Code, Zed Editor, Continue.dev, and custom MCP implementations.

Configure your client to use:

• Command: node
• Args: ["/path/to/kapiti.mcp/build/index.js"]
• Environment: Set HEADLESSHOST_API_KEY

Tools (53)

All tools include MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) to help clients present appropriate UI and confirmation prompts.

General (3)

Tool	Description
ping	Test authentication and connection
health	Check API health status
get_ref_data	Get system reference data and lookups

User Management (4)

Tool	Description
create_user	Create a new user in the current account
get_user	Get user details by ID
update_user	Update user information and claims
delete_user	Delete a user from the system

Account Management (3)

Tool	Description
create_account	Create a new user account
get_account	Get current account information
update_account	Update account information

File Uploads (3)

Tool	Description
upload_user_profile_image	Upload a profile image for a user
upload_staging_site_file	Upload a file to a staging site
upload_staging_site_image	Upload an image to a staging site

Content Sites (5)

Tool	Description
create_content_site	Create a new content site
get_content_sites	Get all content sites in the account
get_content_site	Get content site details by ID
update_content_site	Update content site information
delete_content_site	Delete a content site

Staging Sites (9)

Tool	Description
update_staging_site	Update staging site information
delete_staging_site	Delete a staging site
publish_staging_site	Publish a staging site to make it live
get_staging_site	Get staging site details
get_staging_site_pages	Get staging site pages
get_staging_site_configuration	Get staging site configuration including section types
get_staging_site_logs	Get change logs since last publish
get_published_sites	Get published sites for a content site
revert_staging_site	Revert a staging site to a previous state
clone_staging_site	Clone a staging site

Pages (6)

Tool	Description
create_staging_site_page	Create a new page
get_staging_site_page	Get page details (with optional sections)
update_staging_site_page	Update a page
delete_staging_site_page	Delete a page
revert_staging_site_page	Revert a page to a previous state
get_staging_site_page_logs	Get page change logs since last publish

Sections (7)

Tool	Description
create_staging_site_section	Create a new section in a page
get_staging_site_section	Get section details
update_staging_site_section	Update a section
delete_staging_site_section	Delete a section
publish_staging_site_section	Publish a single section
revert_staging_site_section	Revert a section to a previous state
get_staging_site_section_logs	Get section change logs since last publish

Site Audiences (4)

Tool	Description
create_staging_site_audience	Create an audience (locale/segment combination) for a site
get_staging_site_audience	Get audience details
update_staging_site_audience	Update an audience
delete_staging_site_audience	Delete an audience (base audience cannot be deleted)

Section Audiences (4)

Tool	Description
create_staging_site_section_audience	Create an audience override for a section
get_staging_site_section_audience	Get section audience details
update_staging_site_section_audience	Update a section audience override
delete_staging_site_section_audience	Delete a section audience override

Analytics (4)

Tool	Description
get_content_site_logs	Get the last 15 activity logs
get_content_site_hits	Get daily hit analytics
get_content_site_accounts	Get associated accounts
get_content_site_claims	Get current user claims

Resources

The server provides 2 resources for configuration and monitoring:

• API Configuration (config://api) — Available endpoints and current settings
• API Health Status (health://api) — Real-time connectivity and response time

Development

Build the server:

npm run build

Run in development mode:

npm run dev

Watch for changes:

npm run watch

Run the MCP inspector for debugging:

npm run inspector

Error Handling

The server includes structured error handling:

• API authentication validation
• Network connectivity checks
• Structured logging via MCP logging capability (errors are sent to the client)
• Graceful fallbacks for API timeouts

Security

• API key authentication required for all operations
• Secure environment variable handling
• Input validation via Zod schemas on all tool inputs
• Tool annotations signal destructive operations to clients