Guides

Home / Documentation / MCP

Model Context Protocol

MCP exposes the same site operations you use in the dashboard and REST API to AI agents over Streamable HTTP at /api/mcp. Agents can discover block shapes via schema:// resources and receive precise field-path errors on bad payloads.

Authentication

Pass a Bearer token on every request. Workspace API keys prefixed with sh_live_ work the same as REST v1. Other bearer tokens use the OAuth 2.1 flow advertised from /.well-known/oauth-protected-resource; hosted login completes the authorize step. OAuth issuance needs MCPAUTH_SECRET and an RSA private key in the server environment.

Endpoint

Replace the origin with your deployment host. Example for this environment:

https://slatehut.com/api/mcp

Install

Cursor

One click to add the server — Cursor opens and pre-fills the config. You'll be prompted to enter your API key as the Authorization header value.

Add to Cursor
Manual JSON config
{
  "mcpServers": {
    "slatehut": {
      "url": "https://slatehut.com/api/mcp"
    }
  }
}

Claude Desktop

Add the snippet below to your claude_desktop_config.json. Uses mcp-remote to bridge the HTTP transport. Replace --header with your API key.

{
  "mcpServers": {
    "slatehut": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://slatehut.com/api/mcp"
      ]
    }
  }
}

Recipe: build a site end-to-end

  1. Discover: read schema://blocks for the block catalog and schema://theme for theme enums.
  2. Create: call create_site with a rich prompt, or create_site_from_template if you already know the shape. Pass a subdomain hint to keep URLs memorable.
  3. Refine theme: update_site_theme with hex colors and enum values from the theme schema.
  4. Swap blocks: prefer update_page with blocks:[...] for atomic bulk replacement over looping add_block/delete_block.
  5. Add media: unsplash_search → unsplash_import returns a permanent blob URL plus the photographer attribution you must display.
  6. Iterate: use edit_site for natural-language refinements, or target specific blocks with update_block.
  7. Ship: get_site now returns a public url — share it.

Tools

Sites

create_site
Generate a complete site from a text prompt (title, theme, blocks). Consumes AI credits and 1 create-site quota.
Good first call for “build me a site about X”.
create_site_from_template
Create a site from a built-in template (aiSaas, startup, portfolio, etc.). No AI credits.
list_sites
List sites in the active workspace. Now returns public `url` for each.
get_site
Fetch one site. Optional `include` projects only pages/theme/chrome/meta.
update_site
Patch title, description, theme, and/or replace `pages[]`. Block shapes are validated with a precise field-path error when wrong.
update_site_theme
Patch theme only (merged with existing).
delete_site
Permanently delete a site and detach its domains. Requires `confirm: true`. Frees the create-site quota.
Only path to free a seat on single-site plans.
edit_site
AI-powered natural-language edit that plans and writes changes — same engine as the dashboard editor.
check_subdomain
Check if a subdomain is available before create_site.

Pages

add_page
Add a non-home page. Optional seo & dynamic (CMS) payload.
update_page
Patch title/seo/dynamic. Sending `blocks` replaces the entire block list atomically.
Use this for bulk block swaps instead of looping delete_block.
delete_page
Remove a page. Home page cannot be deleted.

Blocks

list_page_blocks
List blocks on a page. `scope: index | template` for dynamic CMS templates.
get_block
Fetch a single block by id.
add_block
Insert a block at an optional position. Validates `props` against schema://blocks/{type}.
update_block
`props` shallow-merges with existing — pass the full object when replacing.
delete_block
Remove a block. Page must always keep ≥1 block.
reorder_blocks
Reorder by full array of block ids.

Media

upload_image
Upload from a base64 `dataUrl` or fetch a remote `url`; returns public blob URL.
unsplash_search
Search Unsplash. Supports `orientation` (landscape/portrait/squarish) and `color` filters.
unsplash_import
Import a photo to permanent blob storage. Returns `url`, `alt`, and Unsplash `attribution` (always credit the photographer).

CMS

list_collections / get_collection
Browse CMS collections.
create_collection / update_collection / delete_collection
Collection CRUD.
list_items / get_item
Browse CMS items.
create_item / update_item / delete_item
Item CRUD.
attach_dynamic_page
Wire a CMS collection to a dynamic page template.

Domains & submissions

add_domain / list_domains / remove_domain
Custom domain management.
verify_domain / check_domain_verification
DNS verification.
list_form_submissions / list_newsletter_submissions
Read inbox data from forms and newsletter signups.

Templates

list_templates
List built-in site templates (includes previewImageUrl WebP paths).

Resources

Resources are read-only; fetch them with your MCP client’s resource API (e.g. FetchMcpResource in Cursor). Use them before authoring to avoid guess-and-retry on block shapes.

schema://blocks
Index of every block type (short description + props schema name + per-type resource URI).
schema://blocks/{type}
Full JSON schema for one block: shell + props + transitively-referenced components (enums, required fields, nested types).
schema://theme
JSON schema for site.theme (fontPreset, borderRadius, sectionSpacing enums + hex palette) and the merged defaults.
example://blocks/{type}
A concrete valid example block of that type, pulled from a built-in template.
example://sites/{templateId}
Full `pages[]` for a built-in template (aiSaas, startup, portfolio, …) — useful as a reference shape.
site://{subdomain}
Full current site JSON for a subdomain (workspace-scoped).
site://{subdomain}/pages/{pageSlug}
One page (use `_` for home).

Prompts

MCP prompts are pre-built instructions you can invoke with your client's prompt API (e.g. GetMcpPrompt in Cursor). They accept a subdomain argument and expand into a detailed site-creation or editing brief — saving you from writing the same instructions each time. Requires the mcp:prompts OAuth scope.

create-startup-landing-page
SaaS/startup landing with hero, features, and social proof sections.
create-portfolio
Personal or professional portfolio with work showcase.
create-restaurant-site
Restaurant site with menu, hours, and reservation blocks.
create-blog
Blog with article structure and newsletter signup.
create-agency-site
Agency/studio site with services and portfolio.
create-event-page
Event or conference landing with FAQ and registration CTA.
create-ecommerce-landing
Product landing page with gallery and pricing.
create-coming-soon
Minimal coming-soon page with email capture.
edit-polish-copy
Tighten headlines and body copy for conversion.
edit-theme-mood
Adjust theme colors and fonts to match a mood.
edit-add-pricing
Add or refine pricing sections on an existing site.

Block catalog (41 types)

Every block has the shape { id, type, anchorId?, fullWidth?, colorOverrides?, animation?, props }. Fetch schema://blocks/{type} for the exact props schema before adding or updating.

Structure

  • dividerBreathing room, line, or spacer between sections.
  • bannerThin announcement or notification strip with optional link and icon.
  • sectionPaste or write HTML and optional scoped CSS for layouts that are not covered by standard blocks. Optional AI assist to generate markup.

Hero

  • heroHeadline, CTAs, imagery — background fill (gradient, solid, photo), patterns, splits, stacked/full-bleed/centered with optional below-fold image, trust row, highlights.
  • animatedHeroHero with animated gradient, optional word marquee, and floating shapes — extends the standard hero.

Content

  • featuresSelling points: icon grid or alternating image rows (layout + per-item imageUrl/imageAlt), optional subheading.
  • textSimple heading plus paragraph—great for policy or bios.
  • richLong-form content with headings, lists, and formatting.
  • imageTextPhoto or graphic beside a headline and body copy.
  • listManually edited cards or rows (team, services, resources).
  • stepsNumbered or icon steps for your process.
  • timelineMilestones, roadmap, or history.
  • comparisonSide-by-side comparison (not full pricing tables).
  • bentoFeaturesAsymmetric feature cells in a bento-style grid.
  • splitTwo columns for compare-and-contrast stories.
  • calloutHighlighted callout box for tips, warnings, or important notes.
  • featureShowcaseSticky scroll feature sections with alternating media and bullet lists.
  • comparisonTableFull pricing-style comparison table with CTAs per column.

Social proof

  • statsKey metrics in a clean horizontal row.
  • testimonialCustomer quote with name and role.
  • testimonialsMultiple quotes: grid, featured (first quote large), or marquee layout.
  • logosPartner or press logos: text names and/or optional image URLs per logo.
  • teamTeam member grid with avatars, roles, bios, and social links.
  • logoCloudPartner logos in a row, grid, or infinite marquee with optional grayscale.
  • metricsBandAnimated or static KPI band with count-up numbers.

Media

  • imageGalleryRows of images with optional captions.
  • youtubeResponsive embedded video player.
  • marqueeInfinite horizontal scrolling ticker for logos, badges, or short text.
  • gallery3dImage gallery with mosaic, parallax, tilt stack, or coverflow motion.

Commerce

  • ctaSingle focused pitch with one primary button; solid, outline, or muted section variant.
  • pricingPlans with prices, bullets, and sign-up buttons.

CMS

  • collectionListRepeating cards loaded from a content collection (blog posts, directory, etc.).
  • collectionDetailRenders one CMS entry on detail URLs from your collection fields.

Interactive

  • faqAccordion-style questions and answers.
  • mapLocation map visitors can pan and zoom.
  • embedDrop in calendars, widgets, or other iframe tools.
  • formCollect leads and messages—submissions land in your dashboard.
  • newsletterEmail capture section with heading, inline input, and submit button.
  • faqAccordionNative accordion FAQ with grouped, flat, or two-column layout.

Chrome

  • navbarTop bar with your brand, links, and optional CTA.
  • footerBottom links, socials, and copyright.

Error handling for agents

  • Block validation errors now return a field-path list like props.variant: Invalid enum value. Expected 'editorialStart' | 'split' | … plus a hint to fetch the matching schema://blocks/{type}.
  • Quota errors (create_site, ai_site_generation, ai_credits) are returned with a human-readable message. Free plans typically allow 1 site — call delete_site to free the slot before retrying.
  • Concurrency: update_site accepts expectUpdatedAt for optimistic locking; pass force: true to override.
  • 401 on OAuth: verify MCPAUTH_SECRET and an RSA private key are set in your server environment. The OAuth server metadata is available at /.well-known/oauth-authorization-server.
  • Prompts returning empty: confirm your OAuth token includes the mcp:prompts scope. API key auth always has full access.

Cost & quotas

MCP calls share the same rate limits and AI budget rules as REST. create_site and edit_site consume AI credits; deterministic tools (block/page/theme CRUD, media import) do not. See AI credits for plan details.

See also