
Every EmDash site has an MCP server built in at /_emdash/api/mcp, and it is on by default. To connect an AI agent, add that URL to your AI client as a remote MCP server, sign in when the EmDash consent page opens, and untick any permission the agent does not need. From then on the agent can search, draft, edit and schedule content, and it can never do more than the EmDash user who approved it.
What the EmDash MCP server is
MCP, the Model Context Protocol, is a standard way for AI tools to call functions in another system. EmDash exposes its CMS functions as tools: reading and searching content, creating and updating entries, publishing and scheduling, uploading media, managing taxonomies and menus, and restoring revisions.
Your server address is your site address plus the path:
https://example.com/_emdash/api/mcp
On a local install it is http://localhost:4321/_emdash/api/mcp.
The endpoint does not accept anonymous requests, and being signed in to the admin in your browser does not count. Every request needs a bearer token, issued either by an OAuth sign-in or as a personal access token.
Step 1: Decide who the agent acts as
An agent works with the permissions of the EmDash user who connects it, so the user's role is the hard ceiling.
| Role | What a connected agent can do |
|---|---|
| Contributor | Create drafts, edit its own drafts and upload media. It cannot publish. |
| Author | Create content, edit and publish its own content, and upload media. |
| Editor | Manage all content, media, bylines, taxonomies and menus. Read the schema and settings. |
| Admin | Everything, including changing the content model and site settings. |
Our advice: do not connect an agent from your own Admin account for everyday writing. Invite a separate Contributor or Author user and connect from that account. A Contributor agent can draft all day, and a person still decides what goes live.
Step 2: Connect your AI client
Claude
Add your MCP URL as a remote custom connector in Claude's settings. Claude then opens the EmDash sign-in and consent page in your browser. Anthropic controls the connector screens and which plans include them, so follow its current instructions for the exact clicks.
ChatGPT
ChatGPT's developer mode can connect a remote MCP server with OAuth. Create the app with your site's MCP URL, and review each write action before you approve it.
Codex
Add the server from the Codex CLI, then start the sign-in:
codex mcp add emdash-site --url https://example.com/_emdash/api/mcp
codex mcp login emdash-site
Other clients that support remote MCP servers over Streamable HTTP connect the same way. They discover the sign-in endpoints from the site itself, so the URL is all you supply.
Step 3: Trim the permissions on the consent page
When the consent page opens, every permission the client asked for is selected. Clear the ones it does not need before you approve. The token EmDash issues is limited to what you leave ticked and what your role allows, so removing permissions can only reduce access.
| Scope | Lets the agent |
|---|---|
content:read | Read and search content, taxonomies, menus and revisions |
content:write | Create, change, publish, schedule and trash content |
media:read / media:write | View media, or upload, edit and delete it |
schema:read / schema:write | Read collections and fields, or create and delete them |
taxonomies:manage, menus:manage | Edit categories, tags and navigation menus |
settings:read / settings:manage | Read or update site settings |
admin | Call every core tool, including whole-site export and import |
For a writing assistant, content:read, content:write and media:write are usually enough. Leave schema:write and admin off unless the task is a content model change, because deleting a collection or field removes its stored data and cannot be undone.
Step 4: Run a safe first session
You do not need to know tool names. Ask in plain language, in this order:
- "What collections exist, and what fields does the posts collection have?" This makes the agent read your schema before it writes anything.
- "Create a draft blog post about our new opening hours." Saying "blog post" rather than "post" matters when you have several collections.
- "Update the pricing page to mention the new plan." On a published entry this stages a draft. The live page does not change.
- "Compare the live and draft versions of the pricing page." You see exactly what would change.
- "Publish it" or "Schedule it for June 1 at 9am", or open the admin and publish it yourself.
That draft-then-compare-then-publish loop is the main habit to build.
Tokens for scripts and the command line
OAuth suits interactive tools. For an automation with no person at the keyboard, create a personal access token:
- Sign in to the admin as an Administrator and open Settings, then API Tokens.
- Select Create New Token, name it after the job it does, tick only the scopes it needs and set an expiry.
- Copy the token, which starts with
ec_pat_, into your automation's secret store. The token acts as you, so the scopes you tick are what limit it.
The same token works for the MCP endpoint and for the REST API, sent as a header:
Authorization: Bearer $EMDASH_TOKEN
EmDash also ships a command-line tool that covers many of the same jobs. It signs in through the browser and saves the credentials for later commands:
npx emdash login --url https://example.com
npx emdash whoami --url https://example.com
To check that the endpoint is reachable at all, send it a request with no token. A healthy server refuses with a 401 and tells clients where to sign in:
curl -i -X POST https://example.com/_emdash/api/mcp
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource"
Guardrails that are built in
- Two checks on every call. EmDash rejects a tool call when either the token's scope or the user's role is not enough.
- Edit locks. If a person has an entry open in the admin, an agent's write fails with
ENTRY_LOCKEDand the error names who holds it. - Stale-write protection. Each entry carries a revision token. If the entry changed since the agent read it, the update is refused as a conflict and the agent has to read it again.
- Trash before delete. The normal delete tool moves content to trash. Removing it for good is a separate tool, and it needs the Admin role.
- Plugin tools are opt-in. A plugin's tools only appear after an administrator enables them, and the token needs the separate
mcp:toolsscope. Our guide to the EmDash plugin sandbox explains the permission model behind that.
Troubleshooting, and switching it off
The client cannot find the sign-in page. If your site runs behind a reverse proxy, set the public address with EMDASH_SITE_URL or the siteUrl option. Without it EmDash advertises its internal address, which breaks MCP discovery along with passkeys.
The agent says it lacks permission. Look at the error code. INSUFFICIENT_SCOPE means the token was approved without that permission, so reconnect and tick it. INSUFFICIENT_PERMISSIONS means the user's role does not allow the action.
You do not want an MCP endpoint. Turn it off in astro.config.mjs and redeploy:
emdash({
mcp: false,
});
The other EmDash MCP server, for developers
A second, unrelated server at https://docs.emdashcms.com/mcp lets a coding assistant search the EmDash documentation. It is public and read-only, and it cannot see or change your site. Projects created from an EmDash template already include its config files for Claude Code, Cursor and VS Code. To add it to Claude Code by hand:
claude mcp add --transport http emdash-docs https://docs.emdashcms.com/mcp
Further reading
The official AI tools guide lists example prompts for every content type, and the MCP server reference documents every tool and scope. On this site, EmDash vs WordPress compares how the two handle AI agents, and the migration guide covers getting existing content in first. Our AI articles cover the wider topic, and our EmDash team sets up agents with sensible roles and review steps as part of every build.
Frequently asked questions
Is the EmDash MCP server enabled by default?
Yes. EmDash mounts it at /_emdash/api/mcp unless you set mcp: false in the Astro config. It still requires a bearer token, so being enabled does not make anything public.
Can an AI agent publish without anyone reviewing it?
Only if the user it connects as is allowed to publish. Connect the agent from a Contributor account and it can create and edit drafts but not publish them.
Does being logged in to the admin give my AI tool access?
No. Session cookies do not authenticate the MCP endpoint. The client needs an OAuth token that you approve on the consent page, or a personal access token.
What is the difference between the site MCP server and the docs MCP server?
The site server at /_emdash/api/mcp manages your content and needs authentication. The docs server at docs.emdashcms.com/mcp only searches the public EmDash documentation and cannot touch your site.
