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

Authentication options:

• Preferred: per-request OAuth bearer token from the MCP client (ctx.authInfo.token)
• Optional migration fallback: HEADLESSHOST_API_KEY

Set ALLOW_LEGACY_API_KEY_FALLBACK=false to require OAuth tokens and disable legacy fallback.

HTTP auth modes (set MCP_AUTH_MODE):

• none: no auth at MCP edge
• oauth: bearer token required for MCP calls (recommended for ChatGPT)
• mixed: accepts calls with or without bearer token

OAuth metadata env vars:

• MCP_OIDC_ISSUER_URL: your IdP issuer URL (or reuse TOOLS_OIDC_ISSUER_URL)
• MCP_OIDC_AUDIENCE: expected audience (optional metadata hint)
• MCP_PUBLIC_BASE_URL: public MCP URL (for metadata), e.g. https://<ngrok>.ngrok-free.app/mcp

Usage

Local HTTP testing (Streamable HTTP)

Run the server over HTTP on localhost:

MCP_TRANSPORT=http MCP_PORT=3001 npm run dev

MCP endpoint:

http://localhost:3001/mcp

Notes:

• This mode is intended for local testing.
• The current implementation runs stateless Streamable HTTP mode.

ChatGPT OAuth testing (per-user sessions)

1. Start local MCP in OAuth mode:

MCP_TRANSPORT=http \
MCP_PORT=3001 \
MCP_AUTH_MODE=oauth \
MCP_OIDC_ISSUER_URL="https://your-issuer.example.com" \
MCP_OIDC_AUDIENCE="your-api-audience" \
MCP_PUBLIC_BASE_URL="https://your-ngrok-subdomain.ngrok-free.app/mcp" \
ALLOW_LEGACY_API_KEY_FALLBACK=false \
npm run dev

2. Start ngrok:

ngrok http 3001

3. In ChatGPT app setup:

• MCP Server URL: https://your-ngrok-subdomain.ngrok-free.app/mcp
• Authentication: OAuth

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"]
    }
  }
}

Via npx

{
  "mcpServers": {
    "headlesshost-cms": {
      "command": "npx",
      "args": ["headlesshost-mcp-server@latest"],
      "env": {
        "HEADLESSHOST_API_KEY": "legacy-fallback-token-optional",
        "ALLOW_LEGACY_API_KEY_FALLBACK": "true"
      }
    }
  }
}

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": "legacy-fallback-token-optional",
        "ALLOW_LEGACY_API_KEY_FALLBACK": "true"
      }
    }
  }
}

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"]
• Auth (preferred): OAuth bearer token provided by the MCP client
• Optional env fallback: HEADLESSHOST_API_KEY (disable with ALLOW_LEGACY_API_KEY_FALLBACK=false)

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

• OAuth bearer token forwarding for per-user authentication
• Optional legacy API key fallback for migration (HEADLESSHOST_API_KEY)
• Secure environment variable handling
• Input validation via Zod schemas on all tool inputs
• Tool annotations signal destructive operations to clients