Model Context Protocol (MCP) Server

v1.0

Live AI Tooling integration for Claude, Cursor, Windsurf, Copilot, Antigravity, and v0.dev

SaCMS includes a native Model Context Protocol (MCP) Server that bridges your headless CMS content and database schemas directly with modern AI programming assistants. Instead of manually copying schemas, endpoints, or mock JSON into prompt windows, AI agents can dynamically query your schema definitions, inspect content entries, and generate pixel-perfect frontends or TypeScript interfaces autonomously.

How SaCMS MCP Works

1. AI Client (Cursor / Claude)

Issues tool calls over Streamable HTTP or SSE to query content or inspect schemas.

2. SaCMS MCP Server (`/api/mcp`)

Authenticates via Bearer Token, resolves tenant workspace, and executes secure database operations.

3. Live CMS Context

AI receives structured schema fields, single type data, or published records to build complete codebases.

MCP Server Endpoint & Transports

The SaCMS MCP Server supports standard Streamable HTTP and Server-Sent Events (SSE) transports, compatible with all modern MCP-compliant clients.

POST / GEThttp://localhost:3000/api/mcp

• Transport: Streamable HTTP (JSON-RPC 2.0) with SSE fallback

• Protocol Version: MCP Specification 2024-11-05

• Workspace Isolation: Automatically scoped to the tenant workspace bound to the API token

MCP Authentication

All requests to the MCP server must include a valid SaCMS API Token. You can generate a Read-Only API Token in your dashboard under Dashboard → [Tenant] → Developer → API Keys.

1. HTTP Header (Recommended)

Authorization: Bearer YOUR_API_TOKEN

2. Query Parameter (For SSE / Web clients)

/api/mcp?token=YOUR_API_TOKEN

MCP Tool Reference

Complete catalogue of available AI tools and callable methods

14 Tools Available

Get the complete database schema of a SaCMS workspace — all Content Types, Single Types, and Components with their fields and relationships. Call this FIRST before building any frontend or generating types.

This tool takes no arguments. Simply call get_full_schema().

SAMPLE RESPONSE PAYLOAD (JSON)

{
  "workspace": {
    "id": "cmsx45pyb0015ujloxp9f4r6v",
    "name": "My Workspace",
    "slug": "my-workspace"
  },
  "contentTypes": [
    {
      "id": "ct_articles",
      "name": "Articles",
      "slug": "articles",
      "description": "Blog posts and news articles",
      "fields": [
        {
          "name": "Title",
          "slug": "title",
          "type": "text",
          "required": true,
          "unique": false
        },
        {
          "name": "Slug",
          "slug": "slug",
          "type": "slug",
          "required": true,
          "unique": true
        },
        {
          "name": "Content",
          "slug": "content",
          "type": "richText",
          "required": true
        },
        {
          "name": "Author",
          "slug": "author",
          "type": "relation",
          "required": false,
          "relationSlug": "authors"
        }
      ]
    }
  ],
  "singleTypes": [
    {
      "id": "st_homepage",
      "name": "Homepage Config",
      "slug": "homepage-config",
      "description": "Hero banner and featured layout config",
      "fields": [
        {
          "name": "Site Title",
          "slug": "siteTitle",
          "type": "text",
          "required": true
        },
        {
          "name": "Hero Heading",
          "slug": "heroHeading",
          "type": "text",
          "required": false
        }
      ]
    }
  ],
  "components": [
    {
      "id": "comp_seo",
      "name": "SEO Metadata",
      "slug": "seo-metadata",
      "category": "SEO",
      "fields": [
        {
          "name": "Meta Title",
          "slug": "metaTitle",
          "type": "text",
          "required": true
        },
        {
          "name": "Meta Description",
          "slug": "metaDescription",
          "type": "text",
          "required": false
        }
      ]
    }
  ]
}

AI Client & IDE Setup Guides

Step-by-step configuration files and connection instructions for every platform

🟦

Cursor Integration

AI Code EditorStreamable HTTP

Config: Cursor Settings → MCP

Setup Steps

Open Cursor Settings (Ctrl+Shift+J or Cmd+Shift+J)
Navigate to 'Cursor Settings' → 'MCP'
Click '+ Add new MCP server'
Set Type to 'HTTP'
Set Name to 'sacms'
Set Server URL to your MCP URL (e.g. http://localhost:3000/api/mcp)
Add header 'Authorization' with value 'Bearer YOUR_API_TOKEN'
Click Save. A green status dot will confirm the connection is active
In Composer (Agent mode), ask: 'Use the sacms MCP server to get my CMS schema and generate TypeScript types'

CONFIGURATION FILE CONTENT

Cursor Settings → MCP

json

{
  "mcpServers": {
    "sacms": {
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Helpful Tips for Cursor:

• Ensure Agent Mode is active in Cursor Composer to allow autonomous tool calling.

• For remote workspaces or cloud access, expose your local port via Cloudflare Tunnel or ngrok.

Tunneling for Local Development

Connecting cloud AI assistants (v0, Claude Web, etc.) to your local machine

Desktop clients like Cursor and Claude Desktop running on your local machine can directly connect to http://localhost:3000/api/mcp. However, cloud-hosted services like v0.dev or remote IDE instances cannot access your private localhost directly without a secure public tunnel.

Option A: Cloudflare Tunnel (Free & Fast)

bash

cloudflared tunnel --url http://localhost:3000

Copy the generated https://*.trycloudflare.com/api/mcp URL into your AI agent.

Option B: ngrok Tunnel

bash

ngrok http 3000

Copy the resulting forwarding HTTPS address + /api/mcp.

AI Prompt Recipes & Workflows

Ready-to-use prompt templates to supercharge your development in Cursor & Claude

Code Generation

Generate TypeScript Interfaces from CMS Schema

"Please call the SaCMS MCP tool `get_full_schema`. Based on the returned Content Types, Single Types, and Components, generate strongly-typed TypeScript interfaces with JSDoc comments for my frontend application."

Full-Stack Development

Build a Next.js 16 Server Component for Articles

"Use the SaCMS MCP server to inspect the `articles` content type schema and query 5 recent published articles. Then, build a Next.js 16 Server Component with responsive Tailwind CSS styling, ISR caching (`revalidate: 60`), and proper SEO metadata."

UI / UX Design

Construct Landing Page from Homepage Single Type

"Call the `get_single_type_content` tool with `singleTypeSlug: 'homepage'`. Using the returned hero title, subtitles, and CTA buttons, build a modern, high-converting React landing page component."

Interactive Component

E-Commerce Product Catalog with Live Search

"Use `query_content` with `contentTypeSlug: 'products'` to fetch product items. Create a Client Component featuring instant keyword search, category filtering, and price sorting wired to the SaCMS REST API."

Architecture

REST API Integration Guide & Fetch Helper

"Execute `get_api_info` from the SaCMS MCP server. Write a reusable API client utility module (`lib/cms.ts`) with custom error handling, pagination helpers, and TypeScript return types."

SEO & Strategy

Analyze CMS Schema & Suggest SEO Improvements

"Query all content types and components using `get_full_schema`. Analyze the schema fields and recommend missing SEO, OpenGraph, or accessibility metadata fields for each collection."

REST API Documentation

SaCMS provides a powerful, high-performance public REST API to fetch your managed content securely. Built with Next.js 16 App Router, PostgreSQL JSONB, and edge rate-limiting, it supports flexible query parameters, Strapi-compatible filtering, deep population, and full-text search.

Base URL: http://localhost:3000/api/public/[tenant-slug]

REST Authentication

All public REST API requests must include your API key in the headers. You can generate read-only or full-access API keys from your SaCMS Dashboard under Developer Settings → API Keys.

Headers

http

x-api-key: your_api_key_here\n# Or Authorization header:\nAuthorization: Bearer your_api_key_here

TypeScript SDK (@sacms/sdk)

The official SaCMS TypeScript SDK provides a fluent query builder, built-in rate-limit retries, and strongly-typed content models for Next.js 16 (App Router), React, and Node.js.

1. Install Package

Terminal

bash

npm install @sacms/sdk\n# or with Bun:\nbun add @sacms/sdk

2. Generate TypeScript Definitions CLI

Download your workspace schema and generate strongly-typed interfaces automatically:

Terminal CLI

bash

npx @sacms/sdk generate --url http://localhost:3000 --tenant my-workspace --token YOUR_API_KEY --out src/types/sacms.d.ts

3. Next.js 16 App Router Server Component Example

app/articles/page.tsx

typescript

import { SaCMS } from '@sacms/sdk'

// Initialize client (lib/cms.ts)
export const sacms = new SaCMS({
  baseUrl: process.env.NEXT_PUBLIC_CMS_URL || 'http://localhost:3000',
  tenant: process.env.CMS_TENANT || 'my-workspace',
  token: process.env.CMS_API_KEY || 'YOUR_API_KEY'
})

// app/articles/page.tsx (Server Component)
export default async function ArticlesPage() {
  const { data: articles } = await sacms.collection('articles').findMany({
    page: 1,
    pageSize: 10,
    sort: 'createdAt:desc',
  })

  return (
    <main className="max-w-4xl mx-auto py-12">
      <h1 className="text-3xl font-bold mb-6">Latest Articles</h1>
      <div className="grid gap-4">
        {articles.map((article: any) => (
          <article key={article.id} className="p-4 border rounded-xl">
            <h2 className="text-xl font-bold">{article.title}</h2>
            <p className="text-sm text-gray-500 mt-1">{new Date(article.createdAt).toLocaleDateString()}</p>
          </article>
        ))}
      </div>
    </main>
  )
}

Content API (Collections)

Fetch multiple entries of a specific Content Type. Supports pagination, full-text search, field selection, and multi-relational population.

GET/api/public/[tenant]/content/[contentTypeSlug]

Example Request

typescript

fetch('http://localhost:3000/api/public/my-tenant/content/articles?filters[title][$contains]=Next.js&limit=10', {
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
})

Advanced Filtering Operators

SaCMS uses Strapi-compatible filtering syntax: ?filters[field][$operator]=value.

$eq, $neEqual / Not Equal

$gt, $gte, $lt, $lteComparisons

$contains, $startsWithCase-insensitive text match

$in, $notInArray inclusion (comma separated)

$null, $notNullNullability check

Single Types API

Fetch singleton data structures such as Global Navigation, Homepage Hero, or Site Settings.

GET/api/public/[tenant]/single/[singleTypeSlug]

Example Request

typescript

fetch('http://localhost:3000/api/public/my-tenant/single/homepage-settings', {
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
})

GraphQL API Reference

Execute dynamic GraphQL queries and mutations with full field selection, pagination, and relational populate.

POST/api/public/[tenant]/graphql

Query Example

graphql

query GetArticles {
  articles(limit: 5, sort: "createdAt:desc") {
    data {
      id
      title
      slug
      publishedAt
    }
    meta {
      pagination {
        total
        page
        pageSize
      }
    }
  }
}

Bring Your Own Database (BYODB)

Enterprise and Pro workspaces can connect dedicated external PostgreSQL databases and S3 object storage buckets for absolute data isolation and compliance.

⚡ Supabase

Gunakan Connection Pooling URI pada port 6543 atau 5432 direct connection.

postgresql://postgres.xxx:[PASS]@aws-0-ap-southeast-1.pooler.supabase.com:6543/postgres

🌊 Neon DB

Serverless Postgres URL dengan SSL mode require.

postgresql://[USER]:[PASS]@ep-xxx.ap-southeast-1.aws.neon.tech/neondb?sslmode=require

📦 AWS RDS / S3

PostgreSQL RDS instance dan S3 bucket dengan AWS Access Keys.

postgresql://root:[PASS]@mydb.c123.ap-southeast-1.rds.amazonaws.com:5432/sacms

Custom Domains & Cloudflare DNS

Arahkan domain atau subdomain kustom Anda (misal: cms.perusahaan.com) ke SaCMS Cloud untuk white-labeling dashboard dan API endpoint.

Langkah Konfigurasi DNS:

Buka DNS Management di registrar atau Cloudflare Anda.
Tambahkan record CNAME dengan nama subdomain (misal: cms) dan arahkan target ke sacms.cloud.
Masuk ke Dashboard Workspace → Settings → Domains dan klik "Verify Domain".
Sertifikat SSL Let's Encrypt / Cloudflare SSL akan otomatis aktif dalam 1-2 menit.

{ "workspace": { "id": "cmsx45pyb0015ujloxp9f4r6v", "name": "My Workspace", "slug": "my-workspace" }, "contentTypes": [ { "id": "ct_articles", "name": "Articles", "slug": "articles", "description": "Blog posts and news articles", "fields": [ { "name": "Title", "slug": "title", "type": "text", "required": true, "unique": false }, { "name": "Slug", "slug": "slug", "type": "slug", "required": true, "unique": true }, { "name": "Content", "slug": "content", "type": "richText", "required": true }, { "name": "Author", "slug": "author", "type": "relation", "required": false, "relationSlug": "authors" } ] } ], "singleTypes": [ { "id": "st_homepage", "name": "Homepage Config", "slug": "homepage-config", "description": "Hero banner and featured layout config", "fields": [ { "name": "Site Title", "slug": "siteTitle", "type": "text", "required": true }, { "name": "Hero Heading", "slug": "heroHeading", "type": "text", "required": false } ] } ], "components": [ { "id": "comp_seo", "name": "SEO Metadata", "slug": "seo-metadata", "category": "SEO", "fields": [ { "name": "Meta Title", "slug": "metaTitle", "type": "text", "required": true }, { "name": "Meta Description", "slug": "metaDescription", "type": "text", "required": false } ] } ] }

REST API Documentation

Base URL: http://localhost:3000/api/public/[tenant-slug]

import { SaCMS } from '@sacms/sdk' // Initialize client (lib/cms.ts) export const sacms = new SaCMS({ baseUrl: process.env.NEXT_PUBLIC_CMS_URL || 'http://localhost:3000', tenant: process.env.CMS_TENANT || 'my-workspace', token: process.env.CMS_API_KEY || 'YOUR_API_KEY' }) // app/articles/page.tsx (Server Component) export default async function ArticlesPage() { const { data: articles } = await sacms.collection('articles').findMany({ page: 1, pageSize: 10, sort: 'createdAt:desc', }) return ( <main className="max-w-4xl mx-auto py-12"> <h1 className="text-3xl font-bold mb-6">Latest Articles</h1> <div className="grid gap-4"> {articles.map((article: any) => ( <article key={article.id} className="p-4 border rounded-xl"> <h2 className="text-xl font-bold">{article.title}</h2> <p className="text-sm text-gray-500 mt-1">{new Date(article.createdAt).toLocaleDateString()}</p> </article> ))} </div> </main> ) }

query GetArticles { articles(limit: 5, sort: "createdAt:desc") { data { id title slug publishedAt } meta { pagination { total page pageSize } } } }