RFC: Let plugins explicitly declare MCP tools

[jcheese1]

Summary

I would like to propose a plugin-extensible MCP surface for EmDash.

The short version: plugins should be able to explicitly declare MCP tools that EmDash exposes through the existing /_emdash/api/mcp endpoint, alongside core CMS tools.

This would make first-party and third-party plugins naturally usable from agents/chat interfaces without every host application needing to write custom wrappers for each plugin.

Problem

EmDash already has a strong core MCP surface for CMS operations such as content, schema, media, settings, and related admin tasks.

However, plugins often introduce new structured domains that are not well represented by core CMS tools alone. Examples:

• forms: create/update form definitions, list submissions, update submission status
• calendar: create monthly events, bulk-create recurring events, delete schedule entries
• restaurant menu: manage categories, menu items, prices, availability
• reservations: configure slots, blackout dates, capacity
• ecommerce/products: update variants, inventory, prices

Today, a host application can call plugin API routes directly, but each host has to build its own AI tool wrappers around those routes. That works, but it duplicates glue code and means plugin authors cannot ship an agent-friendly interface with the plugin itself.

Proposal

Allow plugins to declare MCP tools explicitly.

A rough shape could look like this:

definePlugin({
  id: "emdash-calendar",
  routes: {
    "events/bulk-create": {
      input: bulkCreateEventsSchema,
      handler: bulkCreateEventsHandler,
    },
    "events/delete": {
      input: deleteEventSchema,
      handler: deleteEventHandler,
    },
  },
  mcp: {
    tools: {
      "calendar.bulkCreateEvents": {
        description:
          "Create or update multiple calendar events. Use this for requests like recurring business days, monthly sale dates, or event schedules.",
        input: bulkCreateEventsSchema,
        route: "events/bulk-create",
      },
      "calendar.deleteEvent": {
        description: "Delete a calendar event by id.",
        input: deleteEventSchema,
        route: "events/delete",
      },
    },
  },
});

Then EmDash MCP could expose:

• core tools: content.*, schema.*, media.*, settings.*, etc.
• plugin tools: calendar.*, forms.*, reservations.*, etc.

Important guardrails

I do not think every plugin route should automatically become an MCP tool.

The safer model is explicit opt-in:

• Plugin authors choose which operations are safe and useful for agents.
• Tool names are namespaced by plugin/domain.
• Input schemas are required and stable.
• Descriptions should say when to use the tool and when not to.
• Destructive tools should be clearly marked or require extra confirmation/scopes.
• Installed/updated plugins that add MCP tools should surface that capability in admin review.
• Token/scoping should ideally distinguish plugin MCP access from unrestricted admin access.

Why not automatic route reflection?

Plugin API routes often include admin-only, internal, destructive, or UI-specific operations. Exposing all of them as tools would make the MCP surface noisy and risky.

Explicit MCP declarations let plugin authors provide a smaller, agent-friendly contract while still using the same underlying route handlers/storage.

Example use case: calendar plugin

A site owner says:

Change Sat and Sun on August to "Unavailable"

An agent could call:

1. calendar.listCalendars
2. calendar.bulkCreateEvents

The plugin would own the structured calendar data and admin UI, while the site theme owns rendering.

Example use case: forms plugin

A site owner says:

Create a new form with Email and Phone Number

An agent could call:

1. forms.listForms
2. forms.upsertForm

This would remove the need for every host to write a custom forms.upsertWebsiteForm wrapper.

Open questions

• Should plugin-declared MCP tools call plugin routes internally, or should they be direct handlers?
• Should tools be enabled by default when a plugin is enabled, or should admins explicitly enable plugin MCP tools?
• How should scopes be represented? Example: plugins:emdash-calendar:write, plugins:emdash-forms:read.
• Should plugin MCP tools appear in the manifest/admin UI for review?
• Should output schemas be supported as well as input schemas?
• How should conflicts be handled if two plugins declare the same tool name?

[ascorbic]

This is a good proposal, and I'd like to see if we can land it. Let me answer your open questions individually, and flag the couple of spots where I'd diverge from the sketch.

1. Call plugin routes internally, or direct handlers?
   Reuse the route mechanism, but not via a literal fetch. A declared tool references an existing plugin route, and invoking the tool dispatches through the same internal path a route call uses: same input validation, same plugin context, same sandbox, same capability check, same audit. So it "calls the route" conceptually, through the in-process dispatcher rather than a real HTTP request. That keeps one execution and security surface instead of a second one to secure, and it means a tool is just { description, input, route } with no separate handler.
2. Enabled by default when the plugin is enabled?
   No. Declaring tools shouldn't be enough on its own. An admin explicitly enables MCP tools for a given plugin. Third-party, agent-callable code should be opt-in, and this pairs with question 4 (we surface the tools for consent at install/update).
3. How should scopes be represented?
   Roughly as you show, but I'd frame it as two independent gates, both required:

• the underlying route's own capability is still enforced, because we dispatch through the route;
• the MCP token carries a scope for plugin-tool access: mcp:tools for all, or mcp:tools:{pluginId} to narrow to one plugin.

I'd avoid minting a full RBAC permission per plugin per verb (plugins:emdash-calendar:write), that's an unbounded surface where every plugin invents its own permissions. The route already declares what capability it needs; the token scope just decides which plugins an agent may reach. I'd also explicitly drop any blanket "caller must be admin" gate, that over-grants and defeats least-privilege agents.
4. Appear in manifest/admin UI for review?
Yes, and I'd make it required rather than optional. If a plugin declares MCP tools, the install/update consent screen lists them (name, description, destructive flag, and the underlying route + capability), and an update that adds a tool re-surfaces for consent. Invocations get audit-logged with provenance (plugin, tool, actor). This is deliberately the same consent story as the plugin registry, so there's one trust surface, not two.
5. Output schemas as well as input?
Yes, optional output schemas (mapping to MCP's outputSchema). Input required, output optional. Mainly I want the manifest field to exist from the start so we're not changing the shape after 1.0; authors can adopt output schemas over time.
6. Duplicate tool names across plugins?
This is the one place I'd diverge from the sketch. Rather than authors choosing a domain like calendar.* (two plugins could both claim calendar), EmDash namespaces every tool by the installed plugin id: the author declares a short local name and we expose it as {pluginId}__{name}. Deterministic, and it removes cross-plugin and core-tool collisions structurally.

Let me know if you want to update your RFC. Otherwise I can draft one and we can get this ready for dev

[oiwa-coder]

thanks! @ascorbic put a PR here: #2002