Atlas MCP Server

MCP (Model Context Protocol) server for Atlas CMS — enables AI agents to manage content.

Docs & dashboard: concepts and API reference live at docs.atlas.latellu.com; the app where you create workspaces, content, and API keys is cms.atlas.latellu.com.

Overview

This MCP server exposes Atlas CMS content management operations as tools for AI agents (Claude, Cursor, etc.). It enables AI agents 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

Building a custom app instead of wiring up an AI agent? Use the @latellu/atlas-sdk TypeScript SDK — this server only exposes tools for MCP clients (Claude Desktop, Cursor, etc.), it isn't a general-purpose HTTP client.

Core Concepts

New to Atlas? A workspace is your tenant — it owns all content types, entries, pages, media, and API keys, isolated from other workspaces. Within a workspace:

• Content type — a schema (e.g. "Article") defining the fields an entry can have.
• Entry — a record of a content type, with a draft → published → archived lifecycle.
• Page — like an entry, but composed of ordered blocks and carries its own SEO metadata.
• Locale — a language variant; localized fields fall back to the workspace's default locale when untranslated.

See the Getting Started guide for the full picture.

Features

Schema & Discovery

• get_workspace_schema — Get all content types, fields, and locales
• list_content_types — List all content types
• get_content_type — Get single content type with fields

Entry Operations

• list_entries — List entries for a content type
• get_entry — Get single entry by slug
• create_entry — Create new draft entry; accepts optional translations: {"<locale>": {"data": {...}}} for localized content
• update_entry — Update existing entry (full replace of data); accepts optional translations: {"<locale>": {"data": {...}}} for localized content
• delete_entry — Delete entry
• publish_entry — Publish draft entry
• unpublish_entry — Unpublish published entry
• archive_entry — Archive entry
• duplicate_entry — Duplicate entry as new draft

Page Operations

• list_pages — List all pages
• get_page — Get page with blocks and SEO
• create_page — Create new draft page; title is an alias for seo.title; seo accepts title/description/keywords/og_image/canonical; blocks are {block_type_id, parent_id?, position, data, translations?} items; accepts optional seo_translations
• update_page — Update page (full replace of data); same schema as create_page
• delete_page — Delete page
• publish_page — Publish page

Media Operations

• get_media — Get media metadata by ID
• upload_media — Upload file from local path
• delete_media — Delete a media file

Notes on Schema & Parameters

• Block Types — When creating or updating pages with blocks, use block_type_id values from get_workspace_schema: look for content types with is_block: true.
• Error Details — Tool errors include per-field validation details and a traceId for debugging server-side issues.

Installation

Using npx (Recommended)

npx @latellu/atlas-mcp

Global Install

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

Configuration

Getting an API Key

1. Open cms.atlas.latellu.com/dashboard/api-keys (sidebar: Developer → API Keys)
2. Click Create API Key, give it a name, pick its scopes, and save
3. 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 docs.atlas.latellu.com/docs/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..."
      }
    }
  }
}

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

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: Server-Side File Validation (enforced by Atlas backend)

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

Best Practices

1. 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 the scope reference for the full list.
2. Restrict upload paths: Only allow necessary directories
3. Rotate keys: Regularly rotate API keys
4. Monitor usage: Review MCP tool calls for suspicious activity

Development

Prerequisites

• Node.js 18+
• npm or yarn

Build

npm run build

Test

npm test

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)       │
         └───────────────────┘

License

MIT License