Plugin-Provided Servers and Scaffolding

Why bundling servers with plugins matters

When a team installs a plugin, they expect it to work — not to then configure five separate tool integrations. Plugins solve this by bundling MCP servers directly. When you enable a plugin, its servers start automatically. When you disable the plugin, the servers disconnect. The plugin handles distribution, and the team gets consistent tooling without any manual MCP setup.

This matters for distribution: instead of sharing a .mcp.json snippet in your documentation and hoping developers add it correctly, you publish a plugin that includes the server. Anyone who installs the plugin gets the server. The mcp-server-dev plugin takes this further by letting Claude scaffold the server for you.

How plugin MCP configuration works

Plugins declare their MCP servers in one of two places: a .mcp.json file at the plugin root, or inline in the mcpServers field of plugin.json. The format is identical to a project .mcp.json. Three special variables expand inside plugin MCP configurations:

The plugin tool and server naming convention

Tools from plugin-bundled servers follow a specific naming pattern:

mcp__plugin_<plugin-name>_<server-name>__<tool-name>

Non-alphanumeric characters in the plugin name or server name are replaced with underscores. For a plugin named my-plugin with a server key database-tools exposing a tool named query, the full callable name is:

mcp__plugin_my-plugin_database-tools__query

Use this full name when referencing the tool in permission rules, hook matchers, and subagent tools fields. A hook matcher written against the bare server key (mcp__database-tools__.*) never fires for a plugin-bundled server.

The server itself registers under the scoped name plugin:<plugin-name>:<server-name>. Use this form in hook configurations that expect a server name rather than a tool name.

Lifecycle: install, reload, disable

Plugin MCP servers activate automatically at session start when their plugin is enabled. If you enable a plugin during a running session, the server does not connect until you run /reload-plugins. The same applies to disabling: the server disconnects after /reload-plugins, not immediately when you disable the plugin.

One important interaction with enterprise policy: deploying managed-mcp.json suppresses all plugin-provided servers in addition to user-configured ones. If your organization uses both managed-mcp.json and plugin distribution, plugin servers will not load unless you explicitly include them in managed-mcp.json or use allowAllClaudeAiMcps for claude.ai-hosted plugins.

Scaffolding a server with mcp-server-dev

The mcp-server-dev plugin generates a working server skeleton from a description of your use case. Install it once:

/plugin install mcp-server-dev@claude-plugins-official

If Claude Code reports the plugin is not found, refresh the marketplace first:

/plugin marketplace update claude-plugins-official

After installing, run /reload-plugins to activate the build command, then:

/mcp-server-dev:build-mcp-server

Claude asks about your use case — what the server should do, which systems it needs to talk to, whether to use stdio or HTTP — and generates a complete server with example tools and the right project structure. The skeleton includes package.json or requirements.txt, a working transport setup, and example tool definitions ready for you to fill in.

Key _meta annotations when building your own server

Three annotations from the MCP specification improve how Claude Code handles your tools:

• anthropic/maxResultSizeChars — raises the output size threshold for a specific tool, up to 500,000 characters. Use this for tools that legitimately return large content like full schemas or file trees.
• anthropic/requiresUserInteraction: true — forces a permission prompt on every call. Use this for consent gates where auto-approval would bypass the human agreement step.
• anthropic/alwaysLoad: true — marks an individual tool for upfront loading even when tool search is enabled. Use this for tools Claude needs on every turn.

The server instructions field is especially important when tool search is enabled. Write it as guidance for when Claude should look for your tools, not as a description of what they do. This is the primary signal Claude uses to decide whether to search for tools from your server in a given task.