Claude Code Plugins Docs: What Plugins Are, How to Install Them, and When to Use MCP Instead

If you are looking for the Claude Code plugins docs, the short answer is this: plugins are the packaging layer for Claude Code extensions. A plugin can bundle skills, agents, hooks, MCP servers, and related config into one installable unit, while MCP remains the tool-connection layer underneath. If you only remember one distinction, remember that plugins package capabilities and MCP connects Claude Code to external systems.

Claude Code now has enough extension surface that the terminology can get muddy fast. “Plugin” often gets used as shorthand for everything, even when the actual feature in play is a skill, a hook, or an MCP server. That confusion matters because the install steps, security model, and maintenance burden are different for each one.

Before we get into setup, one practical note for teams that want more backend flexibility than a closed-model-only workflow: Claude Code’s extension layer is separate from the model you run behind it. That means you can keep the same plugin, skill, and MCP setup while routing inference through an open-weight coding model on Novita AI such as qwen/qwen3-coder-480b-a35b-instruct, which is a credible option for real repository work when you want more cost control without giving up agentic tooling.

What Claude Code Plugins Actually Are

Anthropic’s current docs define plugins as the distribution and reuse layer for Claude Code extensions. In practice, that means a plugin is a self-contained directory with a manifest and optional extension components such as:

• skills
• agents
• hooks
• MCP configuration
• LSP configuration
• helper binaries
• default settings

That is why the official plugin docs matter even if what you really want is a reusable skill or a one-command MCP scaffold. The plugin is often the thing you install, but the behavior you care about lives inside the packaged components.

The most important consequence is naming. Plugin skills are namespaced, so a command from a plugin looks like this:

/my-plugin:hello

That namespace is not cosmetic. It prevents collisions between plugins that ship similarly named commands.

Plugins vs MCP vs Skills vs Hooks

This is where most developers lose time in the docs.

Use this shortcut:

Feature	What it does	Best use case
Plugin	Packages and distributes extensions	Reuse the same setup across projects or teammates
MCP	Connects Claude Code to external tools and services	GitHub, Notion, databases, browser control, internal APIs
Skill	Gives Claude reusable knowledge or a workflow	Review checklists, deploy flows, house style, repeatable prompts
Hook	Runs automatically on lifecycle events	Lint after edits, block risky commands, trigger notifications

A lot of “Claude Code plugin” questions are really MCP questions. If your goal is “connect Claude Code to Jira” or “let Claude query our database,” you are not mainly looking for a plugin feature. You are looking for an MCP server, which may be installed directly or packaged inside a plugin.

That is also why the features overview in the Anthropic docs is useful: it explicitly separates plugins from MCP and from skills. Plugins are the wrapper. MCP is the external connection. Skills are the reusable instructions. Hooks are the automation layer.

From a Novita stack perspective, this is also the cleanest place to separate reasoning from execution. If you are building a custom Claude Code-adjacent workflow around MCP tools, Novita’s LLM API can handle the tool-use reasoning layer while Novita Agent Sandbox handles the isolated execution layer for code, shell commands, and tool side effects. That split maps naturally to the “model decides” versus “runtime executes” boundary that plugin and MCP docs are really describing.

When You Should Use a Plugin

Use a plugin when at least one of these is true:

• you want the same Claude Code customization across multiple repositories;
• you want teammates to install one thing instead of copying .claude/ files manually;
• you want versioned, shareable packaging for skills, hooks, or MCP configs;
• you plan to distribute the extension through a marketplace.

Do not reach for a plugin first if you are only experimenting in one repo. Anthropic’s docs still recommend starting with standalone .claude/ configuration for quick iteration. That is the lower-friction path for project-specific workflows.

In other words:

• standalone config is better for local experimentation;
• plugins are better for portability and distribution.

The Fastest Way to Install an Existing Plugin

If you already know the plugin name and marketplace, the current docs point to the slash-command flow from inside Claude Code.

For example, Anthropic’s MCP docs use this install path for the official mcp-server-dev plugin:

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

If Claude Code reports that the marketplace is missing, add it first:

/plugin marketplace add anthropics/claude-plugins-official

Then rerun the install command.

After installation, check whether Claude tells you to reload plugins. If it does, run:

/reload-plugins

That reload step matters more than it sounds. It is a common reason developers think a plugin “didn’t work” when the files are present but the commands are not active in the current session.

How to Create Your Own Claude Code Plugin

If you want to build your own plugin, the current plugin docs outline a straightforward quickstart:

1. Create a plugin directory.
2. Add .claude-plugin/plugin.json.
3. Add a skills/, agents/, hooks/, or other supported extension directory.
4. Launch Claude Code with --plugin-dir during development.

The smallest useful example is a plugin that ships one skill. Anthropic’s docs show a manifest plus a skills/<name>/SKILL.md folder. The manifest defines the plugin identity, and the skill becomes a namespaced command.

During development, the canonical test flow is:

claude --plugin-dir ./my-first-plugin

Then invoke the skill from inside Claude Code:

/my-first-plugin:hello

One detail that is easy to miss: only plugin.json belongs inside .claude-plugin/. Your skills/, agents/, and hooks/ directories stay at the plugin root, not nested under .claude-plugin/.

Why the Docs Keep Mentioning MCP Inside Plugin Guides

Because a plugin can ship an MCP configuration.

This is useful when you have an internal service that every engineer on your team needs Claude Code to reach. Instead of telling everyone to hand-configure the same MCP server, you can package that config with the rest of your Claude Code workflow.

That does not make MCP obsolete. It just changes how the server gets delivered.

Think about it this way:

• MCP answers: “How does Claude talk to this external system?”
• A plugin answers: “How do we distribute that setup cleanly?”

If you are designing an internal developer platform, that distinction saves a lot of duplicated setup work.

When MCP Is the Better Starting Point

Start with MCP, not a plugin, when the main requirement is external access:

• issue trackers
• monitoring tools
• Slack
• Notion
• databases
• browser automation
• internal HTTP services

Anthropic’s current MCP docs show four common connection modes:

• remote HTTP servers
• remote SSE servers
• local stdio servers
• remote WebSocket servers

For most cloud services, HTTP is the recommended transport. SSE is still documented, but Anthropic marks it as deprecated where HTTP is available.

If you only need to connect one service for yourself, claude mcp add is usually the cleanest place to begin. Wrap it in a plugin later if the setup proves reusable.

MCP gives Claude Code a way to reach tools, but it does not replace a secure execution runtime when one of those tools needs to run code, touch files, or execute commands. In that setup, Novita’s LLM API is the reasoning backend that decides when and how to call tools, while Novita Agent Sandbox is the safer execution environment for the code-running side of the workflow. If your plugin or MCP server is exposing remote code execution, browser automation, or shell-backed helpers, that separation is more than architecture hygiene. It is the difference between “Claude can call this tool” and “this tool runs in an isolated runtime instead of on an engineer’s laptop or shared host.”

A Practical Decision Rule

If you are still unsure which doc page you actually need, use this rule:

• “I want Claude Code to do something the same way every session.” Start with CLAUDE.md or a skill.
• “I want Claude Code to talk to another system.” Start with MCP.
• “I want this setup to be easy to reuse or share.” Package it as a plugin.
• “I want something to run automatically on an event.” Use a hook.

That is more useful than memorizing feature names because it maps directly to the problem you are solving.

A Good Plugin Workflow for Real Teams

For most teams, the cleanest progression looks like this:

1. Prototype the workflow in .claude/ or with direct claude mcp add commands.
2. Keep only the parts that prove useful in real work.
3. Package those parts into a plugin with a clear manifest and namespaced skills.
4. Share it through a marketplace or an internal distribution path.

This avoids the most common failure mode: turning every idea into a plugin before anyone knows whether the workflow is worth maintaining.

If your team is pairing Claude Code with an alternate model backend, this is also the stage where Novita AI can be useful operationally. The plugin and MCP layer stays the same, while model routing can move to Novita’s LLM API for coding-heavy sessions that do not need a premium closed model on every step. That split is often simpler than redesigning the extension stack itself.

Common Mistakes in Claude Code Plugin Setup

These are the mistakes that waste the most time:

Treating every extension as a plugin

Sometimes the right answer is a plain skill or a direct MCP server config. Packaging too early adds maintenance.

Putting files in the wrong directory

plugin.json goes in .claude-plugin/. Skills and hooks do not.

Forgetting namespacing

A plugin skill is invoked with the plugin prefix, not as a global command.

Skipping reload after install

If Claude tells you to run /reload-plugins, do it before assuming the install failed.

Using a plugin when the real need is MCP

If the core problem is tool connectivity, focus on MCP first and package later.

Bottom Line

The Claude Code plugins docs make more sense once you stop treating “plugin” as the only extension concept. Plugins are the distribution layer. Skills hold reusable instructions. Hooks automate lifecycle events. MCP connects Claude Code to external systems.

That framing makes the rest of the docs much easier to navigate. If your goal is fast setup, start with the smallest working unit that solves the problem. Add packaging only when the setup is worth reusing.

FAQ

Are Claude Code plugins the same thing as MCP servers?

No. MCP servers are the connection layer for external tools and services. Plugins are a packaging layer that can include MCP configuration along with skills, hooks, agents, and other Claude Code extensions.

How do I install a Claude Code plugin?

From inside Claude Code, use the /plugin install command with the plugin and marketplace name. If the marketplace is not present, add it with /plugin marketplace add ..., then reload plugins if Claude prompts you to.

Should I use a plugin or just .claude/ files?

Use .claude/ files for quick project-specific iteration. Use a plugin when the setup needs to be reused across projects, shared with teammates, or distributed through a marketplace.

When should I use MCP instead of a plugin?

Use MCP first when your main goal is external access to systems like GitHub, Jira, Notion, Slack, or internal APIs. Package that setup as a plugin later only if you need cleaner reuse and distribution.

Can Claude Code plugins work with non-Anthropic model backends?

Yes. The extension layer and the model backend are separate concerns. In practice, that means you can keep the same Claude Code plugin and MCP setup while routing inference through a compatible provider such as Novita AI for supported coding workflows.

Recommended Articles

• Claude Code Plugins: How MCP Tools Extend Claude Code with External Capabilities
• Claude Code Rules: How to Write CLAUDE.md and Manage Agentic Coding Context
• Build a Remote Code Execution MCP Server with Novita Sandbox and mcp-use Library

Sources checked August 20, 2026: Claude Code features overview, Claude Code plugins docs, Claude Code MCP docs, and Novita AI model library.