MCP Server

Atlas CMS provides an MCP (Model Context Protocol) server that enables AI agents like Claude, Cursor, and others to manage content directly.

Overview

Using Claude Code? The Atlas plugin installs this MCP server pre-configured, plus an agent skill covering the SDK and CLI — one command instead of the manual setup below.

The Atlas MCP server exposes content management operations as tools for AI agents. This allows AI to:

Discover workspace schema (content types, fields, locales)
Read entries, pages, and media
Create, update, publish, and delete content
Upload media files from local filesystem

Installation

Using npx (Recommended)

npx @latellu/atlas-mcp

Global Install

npm install -g @latellu/atlas-mcp
atlas-mcp

Configuration

Getting an API Key

Open cms.atlas.latellu.com/dashboard/api-keys (sidebar: Developer → API Keys)
Click Create API Key, give it a name, pick its scopes, and save
Copy the key — it is only shown once

Key types:

atlas_live_* — Delivery API key. Required for every read tool (get_workspace_schema, list_*, get_*).
atlas_mgmt_* — Management API key. Required for every write tool (create_*, update_*, delete_*, publish_*, unpublish_*, archive_*, duplicate_*, upload_media).

The backend enforces one key type per route group — a management key cannot read /api/v1/public/*, and a delivery key cannot write to /api/v1/manage/*. For the full tool set (read + write), configure both keys. A single key only unlocks the half of the tools matching its type; calling a tool that needs the other key type returns a clear error naming the missing env var.

See Authentication for how scopes work and the full authentication reference.

Environment Variables

Variable	Required	Description
`ATLAS_API_KEY`	One of the three below	Single key, auto-detected by prefix (`atlas_live_` enables read tools, `atlas_mgmt_` enables write tools) — kept for backward compatibility
`ATLAS_LIVE_API_KEY`	No	Delivery key (`atlas_live_*`), explicitly enables read tools
`ATLAS_MGMT_API_KEY`	No	Management key (`atlas_mgmt_*`), explicitly enables write tools
`ATLAS_API_URL`	No	Atlas API base URL (default: `https://api.atlas.latellu.com`)
`MCP_ALLOWED_UPLOAD_PATHS`	No	Comma-separated list of allowed directories for media upload

At least one of ATLAS_API_KEY, ATLAS_LIVE_API_KEY, or ATLAS_MGMT_API_KEY must be set. Set ATLAS_LIVE_API_KEY and ATLAS_MGMT_API_KEY together to enable both read and write tools in the same server.

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "atlas": {
      "command": "npx",
      "args": ["-y", "@latellu/atlas-mcp"],
      "env": {
        "ATLAS_LIVE_API_KEY": "atlas_live_xxx...",
        "ATLAS_MGMT_API_KEY": "atlas_mgmt_xxx...",
        "MCP_ALLOWED_UPLOAD_PATHS": "/Users/you/Documents,/Users/you/Pictures"
      }
    }
  }
}

Write-only setups (no read tools needed) can still set just ATLAS_API_KEY to a single atlas_mgmt_* key.

Cursor Configuration

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "atlas": {
      "command": "npx",
      "args": ["-y", "@latellu/atlas-mcp"],
      "env": {
        "ATLAS_LIVE_API_KEY": "atlas_live_xxx...",
        "ATLAS_MGMT_API_KEY": "atlas_mgmt_xxx..."
      }
    }
  }
}

Available Tools

Schema & Discovery

Tool	Description
`get_workspace_schema`	Get all content types (with `id` and `is_block`), fields, and locales
`list_content_types`	List all content types
`get_content_type`	Get single content type with fields

Entry Operations

Tool	Description	Key Type
`list_entries`	List entries for a content type	Read-only
`get_entry`	Get single entry by slug	Read-only
`create_entry`	Create new draft entry (accepts `translations`)	Management
`update_entry`	Full-replace an existing entry's `data` (accepts `translations`)	Management
`delete_entry`	Delete entry	Management
`publish_entry`	Publish draft entry	Management
`unpublish_entry`	Unpublish published entry	Management
`archive_entry`	Archive entry	Management
`duplicate_entry`	Duplicate entry as new draft	Management

Page Operations

Tool	Description	Key Type
`list_pages`	List all pages	Read-only
`get_page`	Get page with blocks and SEO	Read-only
`create_page`	Create new draft page (`title`, `seo`, `blocks`, `seo_translations`)	Management
`update_page`	Full-replace a page (same shape as `create_page`)	Management
`delete_page`	Delete page	Management
`publish_page`	Publish page (fails if the page has zero blocks)	Management

Media Operations

Tool	Description	Key Type
`get_media`	Get media metadata by ID	Read-only
`upload_media`	Upload file from local path	Management
`delete_media`	Delete media by ID	Management

Media has no update_media tool yet — alt-text/metadata edits after upload aren't exposed via MCP.

Translations: Writing Localized Content

create_entry and update_entry accept an optional translations argument, keyed by locale code, mirroring the shape the Public API returns:

{
  "content_type": "article",
  "data": { "title": "Getting Started with Headless CMS", "summary": "..." },
  "translations": {
    "id": {
      "data": { "title": "Memulai dengan Headless CMS", "summary": "..." }
    }
  }
}

data holds the default-locale values for every field; translations.<locale>.data holds only the localizable fields for that locale — the same required/localizable rules from Localization apply. Put required or localizable values in the wrong place (e.g. a required field only in translations, never in data) and the tool returns a validation error.

update_entry is a full replace

update_entry replaces data (and, per locale, translations) wholesale — it is not a partial patch. Send the complete object you want the entry to end up with, not just the fields that changed.

Composing Pages: SEO and Blocks

create_page and update_page no longer take a bare title field — pages have no title of their own, only seo.title. title is kept as a convenience alias that the server maps to seo.title; you can also set seo directly for full control:

{
  "slug": "home",
  "title": "Atlas CMS — Headless CMS Platform",
  "seo": {
    "description": "Manage and deliver content at scale.",
    "keywords": ["headless cms", "content api"],
    "og_image": "https://cdn.example.com/og.png",
    "canonical": "https://example.com/"
  },
  "seo_translations": [
    { "locale": "id", "seo": { "title": "Atlas CMS — Platform Konten Headless" } }
  ],
  "blocks": [
    {
      "block_type_id": "0190d1a1-0000-7000-8000-000000000020",
      "position": 0,
      "data": { "heading": "Build faster with Atlas" },
      "translations": { "id": { "data": { "heading": "Bangun lebih cepat" } } }
    },
    {
      "block_type_id": "0190d1a1-0000-7000-8000-000000000021",
      "parent_id": "0190d1a1-0000-7000-8000-000000000011",
      "position": 0,
      "data": { "icon": "zap", "title": "Fast delivery" }
    }
  ]
}

Each block needs its block_type_id — the UUID of a block type, i.e. a content type with is_block: true. Call get_workspace_schema first, filter the returned content_types for is_block: true, and use that type's id as block_type_id (field names and shapes for data/translations come from the same schema entry). This makes it possible to author a full page — SEO, nested blocks, and all — from a single get_workspace_schema + create_page round trip, with no dashboard step in between. See Pages for the full block/nesting model.

publish_page requires at least one block

The backend rejects publishing a page with zero blocks. Add at least one block via create_page/update_page before calling publish_page.

Error Messages

Tool errors now include per-field validation detail and a trace ID for support/log correlation, e.g.:

Atlas API error: 400 - Validation failed. (title: title is required) [traceId: req_01hz3k9f8g]

Use the traceId when reporting an issue — it lets the field/reason be looked up in backend logs without re-running the request.

Usage Examples

Schema Discovery

User: "What content types exist in this workspace?"
AI: → Calls get_workspace_schema
    → Returns list of content types with fields

Content Creation

User: "Create a new article about AI"
AI: → Calls get_workspace_schema to understand article fields
    → Calls create_entry with article data
    → Returns created entry with slug

Content Publishing

User: "Publish the article with slug 'ai-intro'"
AI: → Calls publish_entry with content_type='article', slug='ai-intro'
    → Returns published entry

Media Upload

User: "Upload /Users/you/Pictures/tokyo.png as cover image"
AI: → Calls upload_media with file_path='/Users/you/Pictures/tokyo.png'
    → MCP server validates path against allowed directories
    → Uploads file to Atlas
    → Returns media ID and URL

Localized Content

User: "Create that article and add an Indonesian translation"
AI: → Calls create_entry with data (default locale) and
      translations.id.data (Indonesian values for localizable fields)
    → Returns created entry with both locales populated

Page Authoring via Blocks

User: "Build a home page with a hero and a feature grid"
AI: → Calls get_workspace_schema, filters content_types for is_block: true
    → Calls create_page with title, seo, and blocks
      (each block's block_type_id = the matching block type's id)
    → Returns created page with blocks and SEO

Known Limitations

No unpublish_page, archive_page, or duplicate_page tools — pages only support create/update/delete/publish via MCP today.
No bulk operations or block reordering — write one entry/page/block at a time.
No scheduling (publish/unpublish at a future time).
list_* tools use offset pagination only; cursor pagination isn't exposed via MCP (see Pagination & Filtering).
update_media doesn't exist — alt-text/metadata can't be edited after upload.
publish_page fails on pages with zero blocks (backend rule, not MCP-specific).

Security

Permission Model

Layer 1: API Key

atlas_live_* — Read tools only (delivery API)
atlas_mgmt_* — Write tools only (management API)
Configure both (ATLAS_LIVE_API_KEY + ATLAS_MGMT_API_KEY) for the full tool set

Layer 2: Filesystem Permission

Configurable via MCP_ALLOWED_UPLOAD_PATHS env var
Path validation: only files within allowed directories can be uploaded

Layer 3: File Validation

Max 10MB file size
Allowed MIME types: image/*, video/*, application/pdf

Best Practices

Scope API keys: For management keys, grant only the scopes each tool needs — content:write for create/update/delete/reorder, content:publish for publish/unpublish/archive/schedule, media:write for uploads/deletes. Leave unused scopes off. Scopes are picked when you create the key at Developer → API Keys; see Authentication for the full scope reference.
Restrict upload paths: Only allow necessary directories
Rotate keys: Regularly rotate API keys
Monitor usage: Review MCP tool calls for suspicious activity

Architecture

The MCP server connects to Atlas via REST API:

┌─────────────────────────────────────┐
│           MCP Client (AI)           │
│  (Claude Desktop, Cursor, etc.)     │
└──────────────────┬──────────────────┘
                   │
              Stdio Transport
                   │
         ┌─────────▼─────────┐
         │    MCP Server     │
         │  (TypeScript)     │
         └─────────┬─────────┘
                   │
              REST API calls
                   │
         ┌─────────▼─────────┐
         │   Atlas Backend   │
         │  (Go, Echo)       │
         └───────────────────┘

NPM Package

The MCP server is published as an npm package:

Package: @latellu/atlas-mcp
Version: 1.1.0
License: MIT

Authentication — Learn about API keys and scopes
SDK — TypeScript SDK for programmatic access
API Reference — REST API documentation

MCP Server

On this page