SITEHOME
Docs menuConnect a Payload website

Connect a website

Connect a Payload website

Set up official MCP and the extension, create a restricted key, connect.

SiteHome connects to Payload through the official MCP plugin plus two small SiteHome tools for field information and image uploads. Your developer installs these in the website; its owner creates a restricted MCP key and connects in SiteHome. This setup is for new connections. Existing REST/plugin connections are not automatically migrated.

1. Install matching packages and the extension

Use matching Payload and @payloadcms/plugin-mcp 3.92.0 packages. The extension also requires zod 3.25. Follow the extension installation guide and official MCP instructions. Current beta documentation may describe features that stable 3.92.0 does not have.

Copy both index.ts and schema.ts from the extension into the website repository. Register sitehomeMcpTools inside the official plugin's mcp.tools configuration. This is website-side integration code that needs maintenance, rather than a separately published SiteHome npm plugin.

Pass the website's original collection configs, before Payload adds defaults, and the same explicit collection capability configuration to the official plugin and the helper. Include only the intended content collections and their upload-enabled media targets. Enable find, create and update for the chosen content collections and find and create for media. Leave delete disabled. The installation guide contains the complete configuration example.

Keep existing access rules, hooks and validators. The extension supports the official default bearer-key authentication on 3.92.0; custom authentication or another version needs separate adaptation and verification.

What are the two tools for?

The website developer installs these tools once. An agency or customer connecting the site does not need to install them or understand their implementation; they need the website address and a correctly restricted MCP key.

  • `sitehomeSchema` supplies field kinds, labels, choices and relationship targets so SiteHome can show the right editor.
  • `sitehomeUpload` receives new image files through Payload with the linked user's normal rights and validation.

After copying both extension files into a folder named sitehome-mcp-extension, register them as follows. Replace Articles, Media and their slugs with the website's existing collections; retain all other configuration and plugins.

TypeScript
import { buildConfig } from 'payload'
import { mcpPlugin } from '@payloadcms/plugin-mcp'
import { sitehomeMcpTools } from './sitehome-mcp-extension'

const collections = [Articles, Media] // Your existing collection configs
const mcpCollections = {
  articles: { enabled: { find: true, create: true, update: true, delete: false } },
  media: { enabled: { find: true, create: true, delete: false } },
}

// Keep your other configuration and plugins here.
export default buildConfig({
collections,
plugins: [mcpPlugin({
  collections: mcpCollections,
  mcp: { tools: sitehomeMcpTools(collections, mcpCollections) },
})],
})

2. Apply the website's migrations and deploy

The official plugin adds its MCP API-key collection. Review the configuration and any generated database migration using the project's normal process, and run the required migration before deployment. Do not alter existing credentials or weaken access rules. Let the website owner approve deployment.

3. Create a restricted MCP key

  1. Create a dedicated Payload user with access only to the intended content and media collections.
  2. Sign in as that user and create a key under MCP → API Keys. This is an MCP key, not the ordinary user's Enable API Key credential.
  3. Enable the same collection capabilities as above. In the Tools group, explicitly enable sitehomeSchema and sitehomeUpload. Leave delete and configuration-modification tools disabled.
  4. Copy the key and pass it to the website owner securely. Do not put it in source code, chat logs or public environment variables.

The key's linked user must also have the underlying Payload rights. Tool capabilities do not grant content access by themselves.

4. Connect in SiteHome

Choose Connect website → Payload. Enter the address where Payload runs, without /admin, and paste the MCP key. SiteHome checks the connection and field information, shows the readable content collections and connects the ones you choose. Media targets must remain available to support image fields.

The key stays encrypted on the server. Saving a draft in SiteHome does not write to Payload. Publishing starts switched off until a website administrator switches it on; each publication still requires review of the exact changes and an explicit action.

Fields, uploads and publication

The extension identifies field kinds, labels, choices and relationship/media targets. The supported baseline covers scalar fields, supported Lexical rich text with retained unknown nodes, single images and single/multiple/polymorphic relationships. This does not mean every custom Payload control is editable. Unknown controls, arbitrary arrays, galleries, nested groups and localized editing remain outside this scope; SiteHome shows unsupported fields as closed.

sitehomeUpload accepts PNG, JPEG and WebP files up to 10 MiB. It uses Payload's file API with the linked user's access, validation and hooks. An uploaded asset does not itself publish a content item.

Payload owns validation, hooks and access. Their presence does not close an otherwise supported field on this route. SiteHome does not reproduce conditional admin presentation or execute website code. It confirms actual reviewed values and publication status after writing; a hook rewriting input must not be reported as an exact successful publication.

SiteHome checks the schema, source and foreign drafts again immediately before publication. A detected change requires a new review. MCP does not provide an atomic revision guard: a simultaneous change after that check and before the write can still be overwritten. The website owner accepts this limitation; it must not be described as guaranteed protection against concurrent edits.

For an AI coding assistant

Set up official @payloadcms/plugin-mcp@3.92.0 with matching Payload packages and the two-file SiteHome extension, following the installation guide above. Configure explicit content/media capabilities, register sitehomeSchema and sitehomeUpload, and explain how the owner enables both custom tools on their MCP key. Preserve access rules, validation and hooks. Show the configuration and migration diff before the owner deploys. Do not create customer credentials or migrate an existing binding automatically.

Markdown for AI assistants