What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to securely connect to external data sources and tools. With the Headless MCP server, AI assistants like Claude Desktop, VS Code Copilot, and Claude Code CLI can:

• Browse your projects and content types
• Search and retrieve content entries
• Create, update, and publish content (with Editor+ role)
• Manage media assets and folders
• Create content types and fields (with Admin+ role)
• Explore your GraphQL schema
• Use AI-powered semantic search

Getting Started

MCP Server URL

Your MCP server is available at:

https://headless.build/api/mcp

Authentication

The MCP server uses OAuth 2.0 for secure authentication. When you connect an MCP client for the first time:

1. The client will open a browser window
2. You'll log in with your Headless CMS account
3. You'll select which organization to grant access to
4. The client receives a secure access token

Important: Each MCP connection is scoped to a single organization. To access multiple organizations, configure separate MCP server connections.

Client Configuration

Claude Desktop

Add this to your Claude Desktop configuration file:

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "headless": {
      "url": "https://headless.build/api/mcp"
    }
  }
}

VS Code

Add this to your VS Code settings (requires the Copilot MCP extension):

{
  "mcp.servers": {
    "headless": {
      "url": "https://headless.build/api/mcp"
    }
  }
}

Claude Code CLI

Run this command in your terminal:

claude mcp add headless --transport http --url https://headless.build/api/mcp

Available Tools

The MCP server provides 23 tools for managing your CMS content. Your available tools depend on your organization role:

• All roles: 9 read tools for browsing and searching content
• Editor+: 11 additional write tools for content and media management
• Admin+: 2 additional tools for creating content types and fields

list_projects

List all projects in the authorized organization.

Parameters: None

Example response:

{
  "projects": [
    {
      "id": "proj_123",
      "name": "Marketing Site",
      "slug": "marketing-site",
      "description": "Company website content"
    }
  ]
}

get_content_types

List all content types in a project with their field definitions.

Parameters:

• projectSlug (required) - The project slug

Example:

Get content types for project "marketing-site"

list_entries

List content entries in a project, optionally filtered by content type.

Parameters:

• projectSlug (required) - The project slug
• contentTypeApiId (optional) - Filter by content type
• status (optional) - Filter by status (draft, published, archived)
• locale (optional) - Filter by locale
• search (optional) - Search in content fields
• expand (optional) - Populate relationship fields (e.g., ["author", "categories"])
• limit (optional) - Maximum entries to return
• offset (optional) - Number of entries to skip

Example:

List published blog posts with author data expanded

get_entry

Get a single content entry by ID with all field values.

Parameters:

• projectSlug (required) - The project slug
• entryId (required) - The entry ID

list_media

List media assets in a project.

Parameters:

• projectSlug (required) - The project slug
• mimeType (optional) - Filter by MIME type (e.g., image/png)
• search (optional) - Search in filename
• limit (optional) - Maximum assets to return
• offset (optional) - Number of assets to skip

get_schema

Get the GraphQL schema for a project, showing available types and fields.

Parameters:

• projectSlug (required) - The project slug

semantic_search (AI-Powered)

Search content by meaning using AI embeddings. Find entries based on concepts and semantic similarity rather than exact keyword matches.

Parameters:

• projectSlug (required) - The project slug
• query (required) - Natural language search query
• contentTypeApiId (optional) - Filter by content type
• status (optional) - Filter by status (draft, published, archived)
• limit (optional) - Maximum entries to return (default: 20)
• threshold (optional) - Minimum similarity score, 0-1 (default: 0.7)

Example:

Search for blog posts about "customer onboarding strategies"

find_similar (AI-Powered)

Find content entries similar to a given entry based on semantic similarity.

Parameters:

• projectSlug (required) - The project slug
• entryId (required) - The source entry ID
• limit (optional) - Maximum entries to return (default: 10)
• sameContentType (optional) - Only find similar entries of the same type (default: false)

Example:

Find articles similar to entry "abc123"

search_media (AI-Powered)

Search inside documents (PDFs, text files) by content using AI embeddings. Returns matching media assets with the relevant text excerpts.

Parameters:

• projectSlug (required) - The project slug
• query (required) - Natural language search query
• mimeType (optional) - Filter by MIME type (e.g., application/pdf)
• limit (optional) - Maximum assets to return (default: 20)
• threshold (optional) - Minimum similarity score, 0-1 (default: 0.7)

Example:

Search for PDFs mentioning "quarterly revenue projections"

Write Tools (Editor+)

The following tools are available to users with Editor role or higher.

create_entry

Create a new content entry in a project.

Parameters:

• projectSlug (required) - The project slug
• contentTypeApiId (required) - The content type API ID
• data (required) - Field values for the entry
• locale (optional) - Locale for the entry
• slug (optional) - Custom slug for the entry

Example:

Create a new blog post with title "Getting Started" and body content

create_entries

Create multiple content entries in a batch (max 100).

Parameters:

• projectSlug (required) - The project slug
• contentTypeApiId (required) - The content type API ID
• entries (required) - Array of entries, each with data, optional locale, and optional slug

update_entry

Update an existing content entry. Supports optimistic locking via version parameter.

Parameters:

• projectSlug (required) - The project slug
• entryId (required) - The entry ID
• data (optional) - Updated field values
• slug (optional) - Updated slug
• version (optional) - Current version for optimistic locking

Example:

Update entry abc123 to change the title to "New Title"

delete_entry

Permanently delete a content entry.

Parameters:

• projectSlug (required) - The project slug
• entryId (required) - The entry ID

delete_entries

Delete multiple content entries in a batch (max 100).

Parameters:

• projectSlug (required) - The project slug
• entryIds (required) - Array of entry IDs to delete

archive_entry

Archive an entry (soft delete) by changing status to ARCHIVED.

Parameters:

• projectSlug (required) - The project slug
• entryId (required) - The entry ID

publish_entry

Publish a draft content entry.

Parameters:

• projectSlug (required) - The project slug
• entryId (required) - The entry ID

unpublish_entry

Unpublish an entry, reverting it to draft status.

Parameters:

• projectSlug (required) - The project slug
• entryId (required) - The entry ID

publish_entries

Publish multiple content entries in a batch (max 100).

Parameters:

• projectSlug (required) - The project slug
• entryIds (required) - Array of entry IDs to publish

update_media

Update a media asset's metadata (alt text, title, filename).

Parameters:

• projectSlug (required) - The project slug
• assetId (required) - The asset ID
• alt (optional) - Alt text for the asset
• title (optional) - Title for the asset
• filename (optional) - New filename

delete_media

Permanently delete a media asset from storage and database.

Parameters:

• projectSlug (required) - The project slug
• assetId (required) - The asset ID

create_folder

Create a new folder for organizing media assets.

Parameters:

• projectSlug (required) - The project slug
• name (required) - Folder name
• parentId (optional) - Parent folder ID for nested folders

Admin Tools (Admin+)

The following tools are available to users with Admin or Owner roles only.

create_content_type

Create a new content type in a project.

Parameters:

• projectSlug (required) - The project slug
• name (required) - Content type name
• apiId (optional) - Custom API ID (auto-generated if not provided)
• description (optional) - Content type description
• isSingle (optional) - Whether this is a singleton type (default: false)
• draftEnabled (optional) - Enable draft/publish workflow (default: true)

Example:

Create a new "FAQ" content type for frequently asked questions

create_field

Create a new field in a content type.

Parameters:

• projectSlug (required) - The project slug
• contentTypeApiId (required) - The content type API ID
• name (required) - Field name
• apiId (optional) - Custom API ID (auto-generated if not provided)
• fieldType (required) - One of: TEXT, RICH_TEXT, NUMBER, BOOLEAN, DATE, DATETIME, JSON, MEDIA, REFERENCE, SELECT, MULTI_SELECT, COLOR, URL, EMAIL, SLUG, UUID, MARKDOWN
• isRequired (optional) - Whether the field is required (default: false)
• description (optional) - Field description
• validation (optional) - Validation rules object
• settings (optional) - Field settings object

Example:

Add a "publishDate" DATE field to the blogPost content type

Permissions

Your access level through MCP matches your organization role:

Editor+ tools: create_entry, create_entries, update_entry, delete_entry, delete_entries, archive_entry, publish_entry, unpublish_entry, publish_entries, update_media, delete_media, create_folder

Admin+ tools: create_content_type, create_field

Use Cases

Content Management (Editor+)

Create and manage content through your AI assistant:

"Create a new blog post about our product launch"

"Update the pricing page to reflect the new enterprise tier"

"Publish all draft articles from the marketing campaign"

"Delete the outdated press releases from 2023"

Content Discovery

Ask your AI assistant to explore your content:

"What content types are available in the marketing-site project?"

"List the most recent blog posts"

"Show me entries that mention 'pricing'"

Semantic Content Search

Use AI-powered search to find content by meaning:

"Find blog posts about customer onboarding"

"Search for articles related to enterprise security best practices"

"What content do we have about improving user retention?"

Related Content

Discover similar content based on AI analysis:

"Find articles similar to this blog post"

"What other content is related to our pricing page?"

"Show me entries with similar themes to this case study"

Document Search

Search inside PDFs and documents:

"Find PDFs mentioning quarterly revenue"

"Search our documentation for API authentication"

"What documents discuss our refund policy?"

Content Analysis

Have your AI assistant analyze content patterns:

"What fields does the blogPost content type have?"

"How many entries are published vs draft?"

"Show me all entries with the author field populated"

Schema Understanding

Explore your data model:

"Get the GraphQL schema for this project"

"What relationships exist between content types?"

Media Inventory

Browse your asset library:

"List all images in the media library"

"Find media assets matching 'hero'"

Troubleshooting

Authentication not working?

Make sure your browser allows popups from your MCP client. The OAuth flow opens a browser window to authenticate.

Tools not appearing?

Try reconnecting the MCP server:

• Claude Desktop: Restart the application
• VS Code: Use the "Reconnect MCP Server" command
• Claude Code CLI: Run claude mcp restart headless

Getting "Authentication required" errors?

Your OAuth token may have expired. Re-authenticate by triggering an MCP tool call, which will prompt the OAuth flow again.

Connection timeout?

Ensure your Headless CMS deployment is accessible from your network. Check that the URL is correct and the server is running.

Security

The MCP integration follows security best practices:

• OAuth 2.0 with PKCE: Industry-standard authentication with Proof Key for Code Exchange
• Organization-scoped tokens: Each connection is limited to one organization
• Role-based access: Your MCP access matches your organization permissions
• Token expiration: Access tokens expire after 90 days
• No stored credentials: Authentication happens through your browser, not stored in client configs

Dashboard Configuration

You can also view MCP configuration from your organization dashboard:

1. Go to Organization Settings
2. Click MCP in the sidebar
3. View the server URL and configuration examples

This page shows your specific MCP server URL and provides copy-paste configurations for all supported clients.