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

Clone this repository
Install dependencies:
```
npm install
```
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

Headlesshost MCP