MCP Server

The DatoCMS MCP server connects DatoCMS directly to AI assistants through the Model Context Protocol (MCP). It allows MCP-compatible tools, such as Claude Code, Claude Desktop, ChatGPT, Cursor, VS Code, and Windsurf, to interact with your DatoCMS projects using natural language commands.

Already coding locally? Use Agent Skills instead!

If you already have a repo open in your editor or CLI, skip the MCP server and install DatoCMS Agent Skills instead. They automatically install the DatoCMS CLI, which talks directly to the DatoCMS APIs — faster and no MCP server needed. You get everything MCP can do, plus content modeling, frontend integrations, migrations, and plugin expertise.

MCP is the right choice only where there's no local terminal to work in!

What you can do

The DatoCMS MCP server allows AI assistants to:

• Find your projects: Search across every project you have access to (personal account and organizations) and operate on any of them within the same session, without restarting the server or swapping environment variables

• Inspect your schema: Retrieve detailed information about your content models, fields, and relationships

• Execute API operations: Perform both read-only and destructive operations on your DatoCMS project

Requirements

• An MCP-compatible client: Claude Code (recommended), Claude Desktop, ChatGPT, Cursor, VS Code, Windsurf, or other MCP clients

There is nothing to install locally. The server is hosted at https://mcp.datocms.com and authentication happens entirely in your browser through standard OAuth.

Installation

The DatoCMS MCP server uses native MCP OAuth, so configuration only requires the server URL — no API tokens, no environment variables. Choose the installation method for your client:

Claude Code

Use the Claude Code CLI to add the DatoCMS MCP server. Claude Code will open a browser window so you can authorize access through OAuth.

claude mcp add --transport http DatoCMS https://mcp.datocms.com

Codex

Use the Codex CLI to add the DatoCMS MCP server. Codex will open a browser window so you can authorize access through OAuth.

codex mcp add DatoCMS --url https://mcp.datocms.com

Cursor

Go to Cursor Settings → Tools & Integrations → New MCP Server, then paste:

{
  "mcpServers": {
    "DatoCMS": {
      "type": "http",
      "url": "https://mcp.datocms.com"
    }
  }
}

VS Code

Use the VS Code CLI:

code --add-mcp '{"name":"DatoCMS","type":"http","url":"https://mcp.datocms.com"}'

Or follow the MCP installation guide and use the same configuration in your mcp.json.

Claude Desktop / Claude.ai

Claude Desktop and Claude.ai both support remote MCP servers as custom Connectors:

1. Go to Customize → Connectors

2. Click the + button next to Connectors and select Add custom connector

3. Enter a name (e.g. DatoCMS) and the URL https://mcp.datocms.com/

4. Click Add

Once done, click Connect so you can authorize access through DatoCMS OAuth.

ChatGPT

ChatGPT supports remote MCP servers through Developer Mode (currently in beta).

1. Enable Developer Mode at Settings → Apps → Advanced settings → Developer mode

2. Open Apps settings and click Create app next to Advanced settings

3. Enter a name (e.g. DatoCMS), the MCP Server URL https://mcp.datocms.com, and leave Authentication set to OAuth

4. Click Create

Once done, click Connect so you can authorize access through DatoCMS OAuth. The new app will appear in the composer's Developer Mode tool during conversations.

Google Antigravity

In Antigravity Settings → Customizations → Installed MCP Servers, click the Open MCP Config button (or directly open ~/.gemini/antigravity/mcp_config.json):

{
  "mcpServers": {
    "DatoCMS": {
      "type": "http",
      "url": "https://mcp.datocms.com"
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "DatoCMS": {
      "serverUrl": "https://mcp.datocms.com"
    }
  }
}

How it works

Unlike traditional MCPs that expose every API endpoint, the DatoCMS MCP server takes a different approach designed to guide AI assistants through API interactions effectively.

Layered tools, not raw endpoints

DatoCMS has 40+ resources and 150+ API endpoints. Exposing all of them would overwhelm any LLM. Instead, we provide a small set of carefully designed tools organized in three layers (discovery → planning → execution) that guide the AI through a natural workflow:

Discovery & planning — Tools that explore what's available and load the documentation needed for execution:

• search_projects: Search across every project in your account and organizations with fuzzy matching

• list_api_resources: List all available DatoCMS API resources grouped by theme

• get_api_methods: Batch-document any combination of resources, actions, and methods. Returns full TypeScript definitions and examples, and mints the verification tokens that the execution layer requires

• get_schema: Retrieve detailed information about your content models, fields, relationships, and nested blocks

Execution layer (read-only) — These tools use a read-only API token. Most clients allow them to run without confirmation:

• upsert_and_execute_safe_script: Write or patch a TypeScript script and execute it against a read-only client

• view_script: View a previously stored script

Execution layer (read-write) — These tools use a full read-write API token. The user is asked to confirm before each use:

• upsert_and_execute_unsafe_script: Write or patch a TypeScript script and execute it with full create/update/delete permissions

This layered structure reduces malformed API calls and forces the AI to commit to method names before writing code — every API call in a script must reference a verification token returned by get_api_methods.

Documentation-aware

Each documentation tool retrieves detailed method definitions and concrete examples from the official DatoCMS documentation. This is token-intensive, but it significantly improves success rates by giving the LLM the context it needs to make correct API calls.

Script-based execution

Instead of making one API call at a time, the DatoCMS MCP server enables AI assistants to write complete TypeScript programs that batch multiple operations to reduce round-trips and token overhead, provide full context for complex multi-step operations, support incremental editing when errors occur, and get type-checked before execution to catch errors early. Each script runs in an isolated sandbox with restricted network access and a configurable timeout.

Performance & reliability

Real-world performance

When using Claude Code (our recommended client), users report:

• Fast execution: Most common operations complete quickly without noticeable delays

• High success rates: Operations like creating records, adding images, managing translations, and linking records work reliably

• Minimal iteration needed: Most tasks succeed on the first attempt, with occasional minor refinements needed through follow-up prompts

• No missteps: The layered approach effectively prevents malformed API calls

What to expect

Common operations (fast & reliable):

• Creating records with content across multiple fields

• Uploading and attaching images to records

• Adding translations to existing content

• Linking records together

• Copying content between models

• Listing and querying records

Complex operations (slower but functional):

• Very complex operations like generating complete landing pages may take several minutes

• Large batch operations involving many records

• Schema modifications across multiple models

Token consumption

The documentation-aware approach retrieves full method documentation and examples for each operation. This consumes more tokens than traditional MCPs but significantly improves success rates. For most practical tasks, the token cost is acceptable given the reliability and accuracy of results.

Success tips

Results improve with:

• Clear, specific prompts: "Create a blog post with title 'Hello' and attach the uploaded image" works better than "add a post"

• Iterative refinement: If something is missing (like an image), a simple follow-up request handles it quickly

When it works best

The DatoCMS MCP server excels at:

• Everyday content management tasks (creating, updating, translating records)

• Complex multi-step operations that require understanding your content model

• Tasks that would be tedious to do manually (bulk updates, content migration)

• Operations that benefit from type safety and validation

Limits

To keep the service reliable for everyone, scripts that the AI executes inside the sandbox are subject to the following limits. These values apply during the initial beta phase and may change as we gather usage data:

Limit	Free plans	Paid plans
Maximum execution time per script	20 seconds	60 seconds
Weekly sandbox time budget per account	10 minutes	90 minutes
Maximum output captured from a single script	32 KB	32 KB

A few notes on what these mean in practice:

• Per-script timeout: if a script takes longer than the limit it is terminated and the AI receives a friendly error. For long-running operations (large migrations, full-site translations) ask the assistant to split the work into smaller scripts.

• Weekly time budget: every second a script spends running in the sandbox counts against the account's weekly budget. The budget resets on a rolling weekly window. Discovery and documentation tools (get_api_methods, get_schema, etc.) do not consume sandbox time — only upsert_and_execute_safe_script and upsert_and_execute_unsafe_script do.

• Output limit: scripts that produce more than 32 KB of console.log output are truncated. If you need to inspect large datasets, ask the assistant to summarise the result rather than dumping it.

Security

The DatoCMS MCP server is built around the principle that AI assistants generate untrusted code, and that code should never be able to escape its boundaries. Security is enforced at multiple layers.

Native MCP OAuth

There are no API tokens to copy, store, or rotate. The server authenticates through oauth.datocms.com using the standard MCP OAuth flow:

• Tokens never touch your filesystem — your MCP client manages them

• During the authorization step you can scope access to specific projects

• Tokens can be revoked at any time from your DatoCMS account settings; the server detects revoked or expired tokens and prompts a re-authentication

Sandboxed script execution

Every script the AI writes runs in an isolated sandbox separate from any other user's session:

• Network egress is restricted to DatoCMS APIs, your project's asset storage domain, and a whitelist of well-known image services (Unsplash, Pexels, Pixabay, Picsum)

• Credential brokering: scripts never see your real API token. The sandbox transparently injects credentials at the network layer, so a script cannot exfiltrate them — even if it tried

• Read-only enforcement: when the AI uses the safe script variant, the sandbox blocks any non-GET request at the network layer, and the API itself rejects destructive operations

• Type-checking before execution: scripts are validated by the TypeScript compiler before they're allowed to run, catching errors before they reach the API

• Per-script timeouts and weekly time budgets prevent runaway loops and abuse

Script validation

Beyond the sandbox, scripts are statically analysed before execution and rejected if they:

• Use any or unknown type annotations (which would bypass type-checking)

• Cast through never (a common TypeScript escape hatch)

• Include @ts-ignore, @ts-expect-error, or @ts-nocheck comments

• Call API methods that the AI has not pre-declared via get_api_methods (the verification token system)

Troubleshooting

Server not connecting

1. Verify your client supports remote MCP servers (Claude Code, Claude Desktop / Claude.ai via Connectors, ChatGPT via Developer Mode, Cursor, VS Code, Windsurf, and Antigravity all do)

2. Ensure your MCP client configuration uses the correct URL: https://mcp.datocms.com

3. Restart your IDE or client after configuration changes

4. Check that your firewall or corporate proxy allows outbound HTTPS to mcp.datocms.com and oauth.datocms.com

Authentication issues

1. If your token has been revoked or expired, the server will prompt your client to re-authenticate; trigger any DatoCMS tool to start the flow

2. Use the whoami tool to verify which DatoCMS account is currently signed in

3. During OAuth authorization, double-check that you granted access to the projects you want the assistant to work with

4. To switch accounts, sign out from your MCP client (the exact step depends on the client) and trigger a fresh authentication

Script execution failures

1. If the script hits a timeout, ask the assistant to break it into smaller steps

2. If you've exceeded your weekly sandbox budget, wait for the budget to reset or upgrade your plan

Performance issues

If operations are taking too long:

1. Break very complex tasks into smaller steps

2. Use more specific prompts to reduce exploration time

3. Check whether a simpler API method can achieve the same result

Feedback & Contributing

We value your feedback to improve the DatoCMS MCP server:

• Share your experience: Let us know what works well and what doesn't

• Report bugs and suggestions: Reach out at support@datocms.com — your feedback helps us identify common issues, improve documentation, and enhance the server's capabilities

If the AI runs into a bug or gap in our API documentation while using the server, it can use the built-in report_api_issue tool to send a structured report directly to our team.