MCP endpoint and tools

This is the technical reference for the MCP endpoints. Editors who want to connect an AI app should start with Connect AI. Agency admins who work across many clients can use the agency connector, which is one address for every site. This page is for developers, agency admins and anyone who writes their own MCP client or checks what an AI app is allowed to do.

Each site has its own connector URL. AI apps sign in with OAuth 2.1 in the browser, so no secret is pasted into the app. Personal keys still work for scripts and for clients that cannot sign in through a browser. The endpoint belongs to the CMS, not to a site project, so it never uses the site token or the schema token. See tokens.

EndpointCopy Anchor Link

Cookies are not accepted. A request without a bearer credential, or with one that is not an access token or a key, is refused.

AuthenticationCopy Anchor Link

There are two credentials. Apps that use the connector URL sign in with OAuth. Scripts and clients without a browser use a personal key.

OAuth sign-inCopy Anchor Link

The CMS is an OAuth 2.1 authorization server. It follows the MCP authorization specification: the connector URL is a protected resource, the authorization code flow uses PKCE with S256, and clients name the resource they want with RFC 8707 resource indicators. The server is built on @better-auth/oauth-provider.

Discovery. The steps an app takes, in order:

1. It calls the connector URL with no token. The server answers 401 with a challenge that names the protected resource metadata:

   Copy Text

   WWW-Authenticate: Bearer resource_metadata="https://cms.example.com/.well-known/oauth-protected-resource/api/mcp/acme-site", scope="mcp offline_access"

2. It reads the protected resource metadata (RFC 9728) at /.well-known/oauth-protected-resource/api/mcp/<site-slug>. The document names the resource, the authorization server and the scopes:

   Copy Text

   {
     "resource": "https://cms.example.com/api/mcp/acme-site",
     "authorization_servers": ["https://cms.example.com/api/auth"],
     "scopes_supported": ["mcp", "openid", "profile", "email", "offline_access"],
     "bearer_methods_supported": ["header"],
     "resource_name": "Acme Site (Areca CMS)"
   }

   resource is the connector URL exactly, and it is what clients send back as the resource parameter. An unknown site slug answers 404.

3. It reads the authorization server metadata (RFC 8414) at /.well-known/oauth-authorization-server/api/auth, or the OpenID configuration at /.well-known/openid-configuration/api/auth. The issuer is https://<your CMS>/api/auth. The same documents are also served under /api/auth/.well-known/…. Documents at the origin root without the /api/auth path are not served, because their issuer would not match.

Registration. Apps register themselves with Dynamic Client Registration (RFC 7591) at POST /api/auth/oauth2/register. No account is needed, so AI apps can register anonymously. The server accepts https redirect URIs, and http only for loopback addresses (localhost, 127.0.0.1, [::1]), as native apps use. Client ID Metadata Documents are not supported yet, so an app must register through DCR. Registration and token requests are rate limited; see rate limits.

Authorization. The app sends the user's browser to GET /api/auth/oauth2/authorize with these parameters:

The user signs in (with a password, a social or Microsoft sign-in, and a two-factor code if they have one) and then sees the consent screen. See Connect AI. The authorization response carries the iss parameter (RFC 9207), set to the issuer above, so clients can check which server answered.

Token. The app exchanges the code at POST /api/auth/oauth2/token with grant_type=authorization_code, the code_verifier, the same redirect_uri and the resource. The endpoint returns an access token and a refresh token. Refresh with grant_type=refresh_token. Both grants are supported, and no others.

Other endpoints. Revocation is at POST /api/auth/oauth2/revoke (RFC 7009), introspection at POST /api/auth/oauth2/introspect, and user info at /api/auth/oauth2/userinfo. Disconnecting an app on the Connect AI page revokes the same tokens, and it takes effect on the next request.

Scopes. mcp is the only scope the MCP endpoint checks, and it is required. offline_access is needed for a refresh token, so clients usually request it. openid, profile and email are accepted and advertised because common clients request them by default. They identify nothing that the endpoint uses for access.

Lifetimes.

Tokens are opaque, so every request checks them in the database, and revocation takes effect at once. See tokens.

Audience. An access token is valid only for the resource it was issued for. A token issued for acme-site is refused at other-site with 401, and the challenge says the token was issued for a different site.

Per request checks. On every request, the server checks that the token exists, is not expired or revoked, names this site as its resource, and carries the mcp scope. It then checks that the user has an active connection to this site for this app (created by approving the consent screen, not revoked, and used within 90 days). Last, it reads the user's live role on the site. A removed member, a role change or a disconnect takes effect on the next request.

Errors. Failures on the connector URL use the RFC 6750 and RFC 9728 forms:

A client that receives 401 with invalid_token should refresh its token, and start sign-in again if the refresh fails. invalid_grant on refresh means the refresh token is dead, and the app must sign in again.

Personal keysCopy Anchor Link

A key is areca_mcp_ followed by 43 random characters. Areca stores a SHA-256 hash of it, shows it once, and checks it on every request. A key works on the connector URL of its own site, and on /api/mcp. On a connector URL for another site it is refused.

A request is refused with HTTP 401 when the key:

• does not exist, was revoked, or has expired,
• belongs to a user who is no longer a member of the site's client,
• belongs to an agency admin who has no two-factor sign-in, on an installation that requires it (see below).

The /api/mcp endpoint answers with this body and WWW-Authenticate: Bearer realm="areca-mcp". An OAuth access token is not accepted there; use the connector URL for OAuth.

{ "error": "Invalid or expired Areca MCP key" }

An agency admin whose account has no two-factor sign-in is refused with HTTP 403 instead, when the installation requires two-factor for admins (the default):

{ "error": "Your account needs two-factor authentication before AI keys work. Turn it on in Account settings.", "code": "mfa_required" }

The role is read from the database on each request, so a change of role applies to the next request. The Last used time on a key is updated at most once a minute.

Agency connectorCopy Anchor Link

The agency connector at https://<your CMS>/api/agency/mcp gives one AI app access to every client and site an agency admin can manage, production and development. The tools are the same as the per-site tools below, with one difference: every site tool takes a required site argument, the site's slug, and every result includes a site object (slug, name, client, environment).

Agency admins sign in with an app connection (OAuth) or with a personal agency key created on Agency › Connect AI. Keys last 30 days, 90 days, 1 year or never. Both need two-factor sign-in on the account. Anyone who is not an agency admin gets the same 404 {"error":"Site not found"} that an unknown address gets. A site key sent to this address is refused, and an agency key sent to a site's connector is refused with 401.

Navigation toolsCopy Anchor Link

These tools exist only on the agency connector. They are read-only and find the site value for the other tools.

Environment rulesCopy Anchor Link

Every agency tool is listed, whatever kind of site it is for. A call is checked against the site it names:

• Tools for production only (go live, rollback, cancel build, release and build status, schedule and cancel schedule, and create_dev_environment) are refused on a development environment. For release tools the refusal says to push to production first. For scheduling it says scheduling is not available on development environments.
• Tools for development only (refresh_from_production, push_to_production, copy_entry_to_production) are refused on a production site. The refusal says to use the site's development environment slug from list_sites.

A refusal is a normal tool result with isError: true, so the model can explain it and choose the other site.

Going liveCopy Anchor Link

Per-site connectors need the Allow going live tick. The agency connector does not: an agency admin's connection can use go_live, rollback, cancel_build, schedule_entry and cancel_schedule on production sites without it. The OAuth consent screen for the agency connector therefore has no tick box, and says the app can "read and change every client and site, including production, and go live". Per-site connections and keys are unchanged.

Production writes over the agency connector are not blocked. The server instructions ask the model to name the client and the site, and to get the user's confirmation before a production change.

Rules and auditCopy Anchor Link

• Rate limit. The same budget as the per-site connectors, 120 requests a minute for each key or connection, shared across all sites. The per-IP budget applies too.
• Revocation. A key or connection stops working as soon as its owner is no longer an agency admin, is blocked, or loses the second factor. Demoting an agency admin also revokes their agency keys and connections at once.
• Audit. Each change is written to the audit log for the site it changed, with the agency connector as its source and the name of the key or connection that made the call.

Access levelsCopy Anchor Link

Tools are registered per request, based on the caller's current role. A tool that the caller cannot use is not listed by tools/list, and calling it by name returns an error.

The publishing permission is ignored for editors. Both the app's flag and the user's live role are checked on each request.

ToolsCopy Anchor Link

Every tool returns text or JSON. Ids come from earlier tool results. Inputs marked as required must be sent.

Site and schemaCopy Anchor Link

EntriesCopy Anchor Link

Site contentCopy Anchor Link

Site content sections (globals) are single sets of values, such as company details or the home page. They are not collections, so create_entry and list_entries refuse their keys. Use the section key with the tools below, and the section's entry id (from get_global) with the workflow tools.

mark_ready, schedule_entry, cancel_schedule, list_revisions, restore_revision and get_preview_url accept the section's entry id. unpublish_entry, archive_entry and delete_entry refuse it. The preview of a section is its previewPath on the site, so get_preview_url needs that path to be set.

LibraryCopy Anchor Link

PublishingCopy Anchor Link

Workflow (owners)Copy Anchor Link

Languages (agency admins)Copy Anchor Link

Content types (agency admins)Copy Anchor Link

If the site syncs its content types from code, the next manifest push replaces changes made with these tools. Prefer changing the site's configuration.

Development environments (agency admins)Copy Anchor Link

A production site can have one development environment. Agency admins work in it first and push the reviewed changes to production. Its connector URL is site.devEnvironment.connectorUrl in get_site_info, which the production connector gives. The production connector offers create_dev_environment. The development connector offers the tools below, and does not offer the publishing tools (go_live, rollback, cancel_build, list_publications, get_release_status, get_build_job) or the schedule tools. On the agency connector the same tools are listed for every site, and you pass the development environment's slug as site. See Development environments for the workflow.

PromptCopy Anchor Link

The server offers one prompt, write_post, with the arguments collection and topic. It asks the model to read the site and collection schema, draft the content in Markdown, fill in SEO, upload or find images with alt text, create a draft, share the preview URL, and not mark the entry ready or go live unless asked.

LanguagesCopy Anchor Link

On a site with several languages, every content tool that reads or writes text takes an optional locale (a code from get_site_info). Leave it out for the main language. Write one language per call: fields, seo and slug apply to that language. Fields that are not translatable are shared, so they change everywhere; update_entry and update_global list them in sharedFieldsUpdated. Check the other languages with get_entry. Its translations value gives each language's complete flag and missing fields.

On a site with one language nothing here changes, and a locale is refused with a clear message.

Reading entriesCopy Anchor Link

Every entry read returns the same shape. Collection data is under fields, and system values sit at the top level, so a field can never collide with them.

ready means approved, not live. A ready entry can still show live: false until the next go live. Use live and pendingRelease to answer "what is live" and "what is pending". get_release_status lists the pending changes.

Field valuesCopy Anchor Link

Get the exact format for each field from get_collection_schema. The formats are below. Date and datetime fields are content you write, such as an event date. They do not publish or schedule an entry. Use schedule_entry for that.

Unknown field keys are refused, and the error lists the valid keys.

Clearing valuesCopy Anchor Link

On update, a value is cleared with a spelling that matches its type. Leaving a key out keeps its stored value.

Do not send null. The input schema does not accept it for SEO keys.

Rich textCopy Anchor Link

Write rich text as Markdown, never as HTML. Areca converts it to the stored format.

• Use ## for section headings, and ### or #### for subsections. Other heading levels are adjusted to these.
• Separate paragraphs with a blank line. Use **bold**, *italic* and [links](https://…).
• Use bullet and numbered lists, > blockquotes and tables.
• Put images in the text as ![alt text](asset:<assetId>). The asset id must belong to the client's Library, or the write is refused.
• Raw HTML is dropped. An image written with a full https URL is copied into the Library when the entry is saved, and the text then points at the copy. If a copy fails, the image keeps its URL and the result has a warnings list that names it. Uploaded assets are still preferred, because you control their alt text.

When an entry is read back, its images appear as asset:<assetId> in the Markdown, so the same text can be sent again.

SEO objectCopy Anchor Link

The seo argument has these optional keys. To clear one on update, use the spelling in clearing values. Unknown keys are refused. Stored values follow the same limits as the SEO panel in the CMS. See SEO and AI suggestions.

The agent is asked to fill in title, description, focusKeyphrase, summary, keyTakeaways and faq for every new entry. There is no separate SEO-generation tool. The agent writes these values itself.

ErrorsCopy Anchor Link

Errors from tools come back as a normal response with isError: true and a message written for the AI. They are not HTTP errors. Typical messages:

Other failures use HTTP status codes:

• 401 for a missing, invalid, revoked or expired key, as described under authentication.
• 403 with "code": "mfa_required" for an agency admin without two-factor sign-in, as described under authentication.
• 429 when a rate limit is reached, per key (120 a minute) or per client address (600 a minute). The body is { "error": "Too many requests" }, and the Retry-After header gives the wait in seconds. See rate limits.

Uploads from a URLCopy Anchor Link

upload_asset_from_url downloads a file from the public internet and stores it in the client's Library. Areca accepts only:

• JPEG, PNG, WebP, GIF or PDF files. The file's bytes decide the type, not the Content-Type header.
• Files up to 20 MB.
• http or https links on ports 80, 443, 8080 or 8443, without a username or password.
• Addresses on the public internet. Private, local, loopback and link-local addresses are refused, including names that resolve to them.
• Up to three redirects, each checked in the same way.
• Downloads that finish within 15 seconds.

When a download fails, the error begins Could not import the file: and then says why. The main cases are:

The import is recorded in the activity log as an upload ("uploaded … to the Library"). Always pass altText, which describes the image in one sentence.

Upload linksCopy Anchor Link

Most images an AI works with have no public URL: a file on your computer, or a photo you attached to the chat. An AI app can't pass those bytes through a tool call, so Areca gives it an upload link instead. You never need to host an image somewhere first.

1. The AI calls create_asset_upload. It can pass a purpose, such as "Photos for the spring fundraiser post", which the page shows.
2. The files arrive one of two ways:
   • Apps with a shell (Claude Code, Codex, Cursor) send the files themselves: curl -sS -T photo.jpg "<uploadUrl>/", once per file, or curl -sS -T "{a.jpg,b.png}" "<uploadUrl>/". Afterwards they call get_asset_upload with finish: true, which closes the link.
   • Chat apps (claude.ai, ChatGPT, mobile apps) give you the pageUrl. Open it, drop or paste the images (or pick them from your camera roll), check them in the tray, and press Upload. The link closes once everything is in. Then tell the AI you're done.
3. The AI calls get_asset_upload. It gets each file's assetId and a preview of each image, so it can see what you sent, decide where each image goes, and write alt text with update_asset_alt.

The link works without signing in, so treat it like a short-lived password. It stops working once it is used or expires, and also if the person whose AI connection created it loses access to the client. Uploaded files appear in the Library and in list_assets, like any other upload.

Activity and auditCopy Anchor Link

Every change made through a connected app or a personal key is recorded as the user it acts for, with the app's name (or the key's name), so it appears as via AI · name in the activity log. Changes made through the agency connector are recorded with the agency connector as their source and the name of the key or connection. Connecting an app to a site is recorded as mcp_connection.create and disconnecting it as mcp_connection.revoke; personal keys are recorded as mcp_key.create and mcp_key.revoke. The log stores the action and the name, not the text of the content. Changes to a development environment are visible to agency admins only.

RelatedCopy Anchor Link

• Connect AI for editors and owners.
• Tokens for how connections and keys are stored and revoked.
• Rate limits for the sign-in endpoints.
• Permissions matrix for the roles behind each tool.
• Rate limits for the per-key limit.

Scheduling requires Allow going live because the scheduler deploys the site at the chosen time, including other approved changes. Cancelling a schedule remains an owner action. Rich-text image references accept ordinary Markdown titles and reference-style syntax; image examples inside code are not treated as assets.