Model Context Protocol (MCP) Server

v1.0

Live AI Tooling integration for Antigravity and VS Code (GitHub Copilot)

SaCMS includes a native Model Context Protocol (MCP) Server that lets AI assistants query your schemas and content directly, without manual copy-pasting.

How SaCMS MCP Works

1. AI Client (Antigravity / VS Code)

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

37 Tools Available

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

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,
          "localizable": true
        },
        {
          "name": "Content",
          "slug": "content",
          "type": "richText",
          "required": true,
          "unique": false,
          "localizable": true
        },
        {
          "name": "Author",
          "slug": "author",
          "type": "relation",
          "required": false,
          "unique": false,
          "localizable": false,
          "relationSlug": "authors"
        }
      ]
    }
  ],
  "singleTypes": [
    {
      "id": "st_homepage",
      "name": "Homepage Config",
      "slug": "homepage-config",
      "description": "Hero banner and featured layout config",
      "hasData": true,
      "data": {
        "siteTitle": "My Awesome Website",
        "heroHeading": "Welcome"
      },
      "fields": [
        {
          "name": "Site Title",
          "slug": "siteTitle",
          "type": "text",
          "required": true,
          "unique": false,
          "localizable": true
        }
      ]
    }
  ],
  "components": [
    {
      "id": "comp_seo",
      "name": "SEO Metadata",
      "slug": "seo-metadata",
      "category": "SEO",
      "fields": [
        {
          "name": "Meta Title",
          "slug": "metaTitle",
          "type": "text",
          "required": true,
          "unique": false,
          "localizable": true
        }
      ]
    }
  ]
}

Fetch published or draft content entries from a Content Type collection with pagination, search, status, locale filtering, and sort order.

Parameters / Arguments

Field	Type	Required	Default	Description
contentTypeSlug	string	Yes	—	Slug of the Content Type (e.g. 'articles', 'products')
limit	number	No	10	Number of items to return (max 100)
page	number	No	1	Page number (1-indexed)
status	string	No	PUBLISHED	PUBLISHED \| DRAFT \| IN_REVIEW \| ARCHIVED \| ALL
search	string	No	—	Search term
locale	string	No	—	Filter by locale code (e.g. 'id', 'en')
sortOrder	string	No	desc	asc \| desc, sorted by createdAt

SAMPLE RESPONSE PAYLOAD (JSON)

{
  "contentType": "articles",
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 15,
    "totalPages": 2
  },
  "data": [
    {
      "_id": "cmt191h9s000nujikfe9o533b",
      "_status": "PUBLISHED",
      "_locale": "id",
      "_createdAt": "2026-08-20T08:19:09.615Z",
      "_publishedAt": "2026-08-20T08:20:00.000Z",
      "title": "Building Modern Web Apps with Next.js 16 and SaCMS"
    }
  ]
}

AI Client & IDE Setup Guides

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

⚡

Antigravity / AGY Integration

Google DeepMindStreamable HTTP

Config: .agents/mcp_config.json

Setup Steps

Create or open .agents/mcp_config.json in your workspace root
Paste the JSON snippet below with your SaCMS URL and API token
AGY will automatically connect to the MCP server upon startup or task execution
Prompt: 'Check my SaCMS schema and build the corresponding Next.js pages'

CONFIGURATION FILE CONTENT

.agents/mcp_config.json

json

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

Tunneling for Local Development

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

Antigravity and VS Code running on your local machine can directly connect to http://localhost:3000/api/mcp. Remote/cloud-hosted IDE instances cannot reach 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 Antigravity & VS Code

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

A public REST API for fetching your managed content, with 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, generated from 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)

A fluent query builder with built-in rate-limit retries and strongly-typed content models.

1. Install Package

Terminal

bash

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

2. Generate TypeScript Definitions CLI

Introspects your workspace's real schema over the network and generates one interface per Content Type / Single Type — no local database access needed:

Terminal CLI

bash

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

3. Next.js 16 App Router Server Component Example

Pass the generated registry as a type argument for full per-slug intellisense — or skip it and call collection(slug) untyped, returning Record<string, unknown>:

app/articles/page.tsx

typescript

import { SaCMS } from '@sacms/sdk'
import type { SaCMSRegistry } from './types/sacms' // from step 2, optional

// Initialize client (lib/sacms.ts)
export const sacms = new SaCMS<SaCMSRegistry>({
  baseUrl: process.env.NEXT_PUBLIC_SACMS_API_URL || 'http://localhost:3000',
  tenant: process.env.NEXT_PUBLIC_SACMS_TENANT || 'my-workspace',
  token: process.env.SACMS_API_KEY || 'YOUR_API_KEY'
})

// app/articles/page.tsx (Server Component)
export default async function ArticlesPage() {
  const { data: articles } = await sacms.collection('articles').findMany({
    pagination: { 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) => (
          <article key={article.id} className="p-4 border rounded-xl">
            <h2 className="text-xl font-bold">{article.title}</h2>
            <p className="text-sm text-muted-foreground mt-1">{new Date(article.createdAt).toLocaleDateString()}</p>
          </article>
        ))}
      </div>
    </main>
  )
}

4. Member (End-User) Authentication

For apps where visitors sign in themselves — separate from the service token above, which authenticates your backend, not an individual user:

Member auth

typescript

// Sign up or sign in
const session = await sacms.auth.login(email, password)
// session.user, session.accessToken, session.refreshToken, session.expiresIn

// Authenticated calls use that member's own accessToken, not your service token
const { user } = await sacms.auth.me(session.accessToken)
await sacms.auth.updateMe(session.accessToken, { name: 'New Name' })

// Refresh when the access token expires, and sign out when done
const refreshed = await sacms.auth.refresh(session.refreshToken)
await sacms.auth.logout(session.refreshToken)

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

Database Khusus Enterprise

Setiap workspace SaCMS berjalan di infrastruktur PostgreSQL terkelola milik SaCMS dengan isolasi logis per workspace. Untuk kebutuhan isolasi yang lebih tinggi, pemegang Lisensi Enterprise mendapatkan satu database PostgreSQL khusus (dedicated) yang dibuat otomatis saat lisensi diaktifkan — menampung seluruh workspace yang dimiliki akun tersebut. Tidak perlu menyambungkan server atau database eksternal sendiri; semuanya tetap dikelola di infrastruktur 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, "localizable": true }, { "name": "Content", "slug": "content", "type": "richText", "required": true, "unique": false, "localizable": true }, { "name": "Author", "slug": "author", "type": "relation", "required": false, "unique": false, "localizable": false, "relationSlug": "authors" } ] } ], "singleTypes": [ { "id": "st_homepage", "name": "Homepage Config", "slug": "homepage-config", "description": "Hero banner and featured layout config", "hasData": true, "data": { "siteTitle": "My Awesome Website", "heroHeading": "Welcome" }, "fields": [ { "name": "Site Title", "slug": "siteTitle", "type": "text", "required": true, "unique": false, "localizable": true } ] } ], "components": [ { "id": "comp_seo", "name": "SEO Metadata", "slug": "seo-metadata", "category": "SEO", "fields": [ { "name": "Meta Title", "slug": "metaTitle", "type": "text", "required": true, "unique": false, "localizable": true } ] } ] }

Field

Type

Required

Default

Description

contentTypeSlug

string

Yes

—

Slug of the Content Type (e.g. 'articles', 'products')

limit

number

Number of items to return (max 100)

page

number

Page number (1-indexed)

status

string

PUBLISHED

PUBLISHED | DRAFT | IN_REVIEW | ARCHIVED | ALL

string

—

Search term

locale

string

—

Filter by locale code (e.g. 'id', 'en')

sortOrder

string

desc

asc | desc, sorted by createdAt

{ "contentType": "articles", "pagination": { "page": 1, "limit": 10, "total": 15, "totalPages": 2 }, "data": [ { "_id": "cmt191h9s000nujikfe9o533b", "_status": "PUBLISHED", "_locale": "id", "_createdAt": "2026-08-20T08:19:09.615Z", "_publishedAt": "2026-08-20T08:20:00.000Z", "title": "Building Modern Web Apps with Next.js 16 and SaCMS" } ] }

import { SaCMS } from '@sacms/sdk' import type { SaCMSRegistry } from './types/sacms' // from step 2, optional // Initialize client (lib/sacms.ts) export const sacms = new SaCMS<SaCMSRegistry>({ baseUrl: process.env.NEXT_PUBLIC_SACMS_API_URL || 'http://localhost:3000', tenant: process.env.NEXT_PUBLIC_SACMS_TENANT || 'my-workspace', token: process.env.SACMS_API_KEY || 'YOUR_API_KEY' }) // app/articles/page.tsx (Server Component) export default async function ArticlesPage() { const { data: articles } = await sacms.collection('articles').findMany({ pagination: { 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) => ( <article key={article.id} className="p-4 border rounded-xl"> <h2 className="text-xl font-bold">{article.title}</h2> <p className="text-sm text-muted-foreground mt-1">{new Date(article.createdAt).toLocaleDateString()}</p> </article> ))} </div> </main> ) }

// Sign up or sign in const session = await sacms.auth.login(email, password) // session.user, session.accessToken, session.refreshToken, session.expiresIn // Authenticated calls use that member's own accessToken, not your service token const { user } = await sacms.auth.me(session.accessToken) await sacms.auth.updateMe(session.accessToken, { name: 'New Name' }) // Refresh when the access token expires, and sign out when done const refreshed = await sacms.auth.refresh(session.refreshToken) await sacms.auth.logout(session.refreshToken)

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