Claude Code Plugins: How MCP Tools Extend Claude Code with External Capabilities

Claude Code does not have a traditional plugin system with a marketplace and one-click installs. What it has instead is the Model Context Protocol (MCP) — an open standard from Anthropic that lets you attach any external tool to a Claude Code session. MCP servers function as plugins: they expose callable tools, Claude reasons about when to use them, and the result feeds back into the conversation. This guide covers how that system works, how to install real servers, and how Novita AI’s LLM API and Agent Sandbox fit into tool-heavy workflows.

What “Claude Code plugins” actually means

When developers search for “Claude Code plugins,” they usually want one of three things: a way to give Claude Code access to an external service (GitHub, a database, a web browser), a way to install community-built tool extensions, or documentation on how the extension mechanism works.

All three lead to MCP. Anthropic designed Claude Code around the Model Context Protocol rather than a proprietary plugin format. This means:

• No separate marketplace: tools are distributed as MCP servers, not through a platform-specific registry
• No API-level lockout: any developer can build a server and share it
• Same integration surface: Claude Code, Claude Desktop, and other Claude hosts all use the same protocol

The practical effect is that Claude Code’s plugin catalog is the MCP ecosystem — any server built to the MCP spec works with Claude Code, and thousands already exist for databases, APIs, browsers, code runners, file systems, and more.

There is no claude plugin install command. The equivalent is claude mcp add.

How MCP servers work as plugins

Each MCP server is a process that exposes a set of tools through the MCP protocol. Claude Code launches or connects to registered servers when you start a session, queries them for their tool lists, and then uses those tools when the conversation calls for it.

Three things make up an MCP server’s interface:

Object	What it is	Example
Tool	A callable function with defined inputs and outputs	run_python, search_docs, create_issue
Resource	Read-only data the server exposes as context	A file contents, a database row, a test fixture
Prompt	Pre-built instruction templates bundled with the server	A code review checklist, a task template

For most Claude Code workflows, tools are what matter. Resources and prompts come into play when you’re building more structured agentic pipelines.

The key protocol sequence:

1. Claude Code starts, reads its config, and launches registered servers
2. Each server responds to a tools/list query with names and JSON Schema definitions
3. During a session, Claude uses those definitions to decide when and how to call each tool
4. Claude Code dispatches the call, the server executes and returns the result, Claude incorporates the result and continues

The server handles execution. Claude handles reasoning about when execution is needed.

Installing your first plugin with claude mcp add

claude mcp add is the command that registers an MCP server with Claude Code. Run it once; the server is available in every subsequent session.

# Basic form for stdio servers
claude mcp add <server-name> -- <command> [args...]

# Basic form for HTTP servers
claude mcp add --transport http <server-name> <url>

Prerequisites before running any claude mcp add command:

• Claude Code installed and on your PATH (claude --version should work)
• Node.js 18 or later for npm-based servers
• Python 3.10 or later for Python-based servers

Adding the Playwright browser plugin

The Playwright MCP server gives Claude a real browser — it can navigate URLs, click elements, extract text, and return screenshots. This is one of the most useful first plugins to add because it requires no API key and immediately demonstrates what the protocol can do.

claude mcp add playwright -- npx -y @playwright/mcp@latest

Verify it registered:

claude mcp list

Then open a session:

Use playwright to open https://example.com and tell me the page title and main heading

Claude will launch a browser, navigate to the URL, read the DOM, and return the answer — no scripting required on your part.

Adding a database plugin

The official SQLite MCP server lets Claude query and inspect a local SQLite database directly from conversation:

claude mcp add sqlite -- uvx mcp-server-sqlite --db-path /path/to/your/database.db

After that, you can ask Claude to write queries, explain schema, or explore data directly without copy-pasting schema definitions into every prompt.

Passing environment variables

Most API-backed servers need keys. Use --env to pass them at registration time without embedding them in the command:

claude mcp add linear -- npx -y @linear/mcp-server \
  --env LINEAR_API_KEY=your_key_here

The values are stored in Claude Code’s config and injected into the server process at startup.

Scopes: local, project, and user

By default, claude mcp add registers a server at local scope — it’s active only when Claude Code is started from the current directory. Three scope options give you different sharing models:

Scope	Active in	Config file	When to use
local (default)	Current directory only	~/.claude.json	Personal dev server for one project
project	Any session inside this repo	.mcp.json in project root	Team tool — commit alongside the code
user	Every Claude Code session	~/.claude.json under user scope	Global tools you always want available

Add --scope project to commit the server definition with your repo:

claude mcp add sqlite --scope project -- uvx mcp-server-sqlite --db-path ./dev.db

This creates .mcp.json at the project root with the server definition. Teammates who run Claude Code in the same repository get the same tool available automatically — no per-developer setup beyond having the prerequisites installed.

For user-scoped tools that make sense everywhere:

claude mcp add playwright --scope user -- npx -y @playwright/mcp@latest

Popular MCP plugins and what they do

The MCP ecosystem has grown substantially since Anthropic published the protocol. Some categories with real-world usage:

Development tools

Server	What it adds
@playwright/mcp	Browser automation — navigate, click, extract, screenshot
@modelcontextprotocol/server-git	Read commits, diffs, branches, blame from local repos
@modelcontextprotocol/server-filesystem	Scoped filesystem access — read/write files in defined paths
mcp-server-sqlite	Query and inspect SQLite databases

Services and APIs

Server	What it adds
@linear/mcp-server	Create, read, and update Linear issues
@sentry/mcp-server	Query Sentry errors and traces
@modelcontextprotocol/server-github	GitHub repos, issues, PRs, and code search
@notionhq/notion-mcp-server	Read and write Notion pages and databases

AI and code execution

Server	What it adds
Novita Sandbox MCP server	Isolated Python/Node execution in cloud sandboxes
@modelcontextprotocol/server-memory	Persistent key-value memory across sessions

These are installable through claude mcp add with npx for npm-based packages or uvx/pip for Python packages.

How Claude routes tool calls at runtime

Claude doesn’t call tools randomly or exhaustively. It reasons about which tool (if any) is appropriate for each step in a task, based entirely on the tool’s description.

The routing logic at a high level:

1. At session start, Claude queries all registered servers and builds a tool catalog
2. For each user message or task step, Claude evaluates whether any tool description matches what’s needed
3. If a match looks promising, Claude constructs a call with appropriate arguments based on the tool’s JSON Schema
4. Claude Code dispatches the call, waits for the result, and incorporates it before the next step

One consequence: tool descriptions are load-bearing. A vague description like "useful tool" will result in the tool never being called. A description that says exactly what the tool does, when to call it, and what its inputs and outputs look like leads to accurate, reliable use.

If you build your own MCP server and tools are not being called despite being registered, the description is almost always the issue — not the implementation.

Claude can also chain tool calls within a single turn: read a file to understand context, search for a dependency, run a test, check the output, and suggest a fix — each step using a different tool from a potentially different server.

Running plugin execution in a sandbox

When plugins execute code — Python scripts, shell commands, browser automation — running them on your local machine carries risk. A tool with file system access or process spawning has a broad surface if it misbehaves or receives a malformed prompt.

Novita Agent Sandbox addresses this by providing isolated cloud environments for tool execution. Instead of running your MCP server locally, you deploy it inside a sandbox instance. The sandbox gets its own filesystem, network scope, and resource limits. Tool execution happens inside that boundary without touching the host machine.

From Claude’s perspective, the integration is identical — the tool list looks the same, and calls work the same way. The difference is entirely where execution runs.

Key characteristics of Novita Sandbox for MCP tool execution:

• Fast startup: instances launch in under ~200ms on average, keeping tool round-trip latency low
• Per-second billing: you pay only for active execution time, not idle reservation
• Isolated filesystem: each sandbox instance has a separate workspace, preventing cross-session leakage
• Configurable network scope: control which external services the tool can reach

To use the Novita Sandbox SDK inside an MCP tool handler:

pip install novita-sandbox

from novita_sandbox.code_interpreter import Sandbox

def execute_code(code: str, api_key: str) -> dict:
    sandbox = Sandbox.create(
        template="code-interpreter-v1",
        api_key=api_key,
        domain="sandbox.novita.ai",
        timeout=300,
    )
    result = sandbox.run_code(code, language="python")
    sandbox.kill()
    return {
        "output": result.logs,
        "error": result.error,
    }

The code-interpreter-v1 template comes with pandas, numpy, matplotlib, and other common packages pre-installed. For a full walkthrough, see Build a Remote Code Execution MCP Server with Novita Sandbox and mcp-use Library.

Using Novita LLM API for tool-use reasoning

Claude Code handles tool-use reasoning using whatever model is configured as its backend. If you’re routing Claude Code through an alternative provider — for cost, latency, or model access reasons — the reasoning layer for tool calls routes through that provider too.

Novita LLM API provides an Anthropic-compatible endpoint at https://api.novita.ai/anthropic. Configure it once with three environment variables:

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_AUTH_TOKEN="your-novita-api-key"
export ANTHROPIC_MODEL="qwen/qwen3-coder-480b-a35b-instruct"
export ANTHROPIC_SMALL_FAST_MODEL="deepseek/deepseek-v4-flash"

With this setup, Claude Code’s MCP tool calls continue to work exactly as before. The routing affects which model does the reasoning — not the tool dispatch mechanism, which stays at the Claude Code layer.

Model choices for tool-heavy sessions:

• Qwen3-Coder 480B — well-suited for long-horizon tasks where Claude needs to read many files, plan a multi-step sequence, and call tools at each stage. Its long context handling keeps earlier tool results accessible throughout a complex session.
• MiniMax M2.7 — optimized for agentic tool-use accuracy, specifically designed to reduce incorrect tool invocations and handle multi-turn sequences where each step builds on the previous result.
• DeepSeek V4 Flash — fast and cheap, a good choice for ANTHROPIC_SMALL_FAST_MODEL. Claude Code uses this slot for session summarization and context compression, neither of which requires deep reasoning.

If you’re building your own MCP host (rather than using Claude Code), the Novita LLM API also provides an OpenAI-compatible endpoint at https://api.novita.ai/v3/openai for models that support function calling:

import openai

client = openai.OpenAI(
    base_url="https://api.novita.ai/v3/openai",
    api_key="your-novita-api-key",
)

response = client.chat.completions.create(
    model="meta-llama/llama-3.3-70b-instruct",
    messages=[{"role": "user", "content": "List available tools and run a quick check"}],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "list_files",
                "description": "List files in the current working directory.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "path": {
                            "type": "string",
                            "description": "Directory path to list."
                        }
                    },
                    "required": ["path"]
                }
            }
        }
    ],
    tool_choice="auto",
)

This is particularly useful for scenarios where you want an open-weight model to act as the reasoning layer in a custom MCP pipeline, with different cost or latency characteristics than closed models.

Open-weight models as an alternative backbone

One underappreciated option for MCP-heavy Claude Code workflows is replacing the default Claude model entirely with a capable open-weight alternative. Models like Qwen3-Coder, MiniMax M2.7, and DeepSeek V3.1 have been trained specifically for tool-calling accuracy and multi-step reasoning — in some benchmarks these match or exceed closed-source models on function-calling tasks, at a fraction of the cost.

For teams running high-volume agent sessions — CI pipelines, automated code review, batch refactoring — the cost difference matters. Novita AI provides access to these models through the same Anthropic-compatible endpoint, so the switch is a configuration change, not a code rewrite.

Writing tool descriptions that work

If you’re building your own MCP server for Claude Code, the quality of your tool descriptions determines whether Claude uses your tools effectively. This is the single highest-leverage thing you can do for a custom server.

A tool description that works answers three questions:

1. What does the tool do? — concrete, not abstract
2. When should it be called? — the scenario or trigger condition
3. What are the inputs and outputs? — enough for Claude to construct correct arguments

Compare these two descriptions for the same search_codebase tool:

Poor: "Searches the codebase."

Effective: "Searches source files in the current repository for a symbol, string, or regex pattern. Call this when you need to find where a function is defined, locate all usages of a variable, or identify which files reference a particular module. Returns a list of file paths with matching lines and line numbers."

The second description tells Claude when to call the tool (not just what it does), which produces far more accurate and timely invocations.

A few additional practices:

• Mark mutating tools clearly: If a tool writes to a database or deploys code, say so explicitly. Claude will be more careful about calling it without clear evidence the action is intended.
• Explain return shapes: If the tool returns a JSON object with a specific structure, describe the key fields. Claude uses this to extract the right information for the next step.
• Keep scopes narrow: A tool named "run_anything" that accepts arbitrary shell commands is harder for Claude to reason about than "run_tests" that runs the project test suite. Narrow tools with precise descriptions work better than broad tools with vague ones.

Troubleshooting common plugin issues

Tool not appearing after claude mcp add

Check that the server command runs without error in a fresh terminal. Claude Code may suppress subprocess stderr. Run claude mcp list — if the server shows a timeout or error, the command itself is failing, not the configuration.

Tools registered but never called

The tool descriptions are too vague. Rewrite them to specify when Claude should call the tool and what the arguments mean.

npx hangs on first run

Add the -y flag to auto-accept the install prompt: npx -y @package/mcp-server. Without it, npx waits for user confirmation and Claude Code sees a connection timeout.

Server not active in a new project

You registered at local scope and started Claude Code from a different directory. Re-add at --scope user for a global server or run the add command from the correct project root.

Tool calls fail with schema validation errors

Claude constructs arguments based on the tool’s JSON Schema. If required fields are missing from the schema or types don’t match, the server rejects the call. Review your inputSchema definition — incomplete schemas lead to incomplete call arguments.

claude mcp add command not found

Install Claude Code: npm install -g @anthropic-ai/claude-code, then verify with claude --version.

FAQ

Does Claude Code have a plugin marketplace?

Not in the traditional sense. Claude Code uses the MCP protocol rather than a platform-specific marketplace. Community-built MCP servers are published on npm, PyPI, and GitHub. Some aggregators maintain curated lists, but there is no official Claude Code marketplace to browse.

What is claude code plugins documentation?

Anthropic’s official documentation for Claude Code’s MCP integration lives at docs.anthropic.com/claude-code. The MCP specification itself is at modelcontextprotocol.io. These are the two sources to reference for authoritative protocol and implementation details.

How is an MCP server different from a Claude Code plugin?

The terms refer to the same thing in Claude Code’s context. When developers say “Claude Code plugin,” they typically mean an MCP server connected to Claude Code. The word “plugin” is not Anthropic’s official terminology, but the concept maps directly: install once, use in every session, extends Claude’s capabilities with new tools.

Can I use the same MCP server in Claude Desktop and Claude Code?

Yes. The server is protocol-agnostic — it doesn’t care which host connects. For stdio servers, both Claude Code (via claude mcp add) and Claude Desktop (via JSON config file) can launch the same command. For HTTP servers, any host that can reach the URL can connect.

How many MCP servers can I register?

The MCP protocol and Claude Code impose no hard limit. Practically, having many servers with hundreds of tools can slow session startup (tool discovery runs at launch) and add noise to Claude’s tool selection. Keep the active set focused on what a given session actually needs.

Are there security risks to adding MCP plugins?

Yes. MCP servers run as processes with whatever permissions they need to do their jobs. A server with file system access can read or write files; one with shell execution can run arbitrary commands. Only add servers you trust. For production or shared environments, consider running servers in isolated environments — see the sandbox section above.

Do open-weight models support MCP tool calling?

Yes. Models that implement function calling in the Anthropic message API format work with Claude Code’s MCP layer regardless of provider. Qwen3-Coder, MiniMax M2.7, and DeepSeek V3.1 all support structured tool calling. The tool dispatch is handled by Claude Code; the model only needs to return valid tool call instructions in the expected format.

---

Recommended Articles

• Claude MCP Add Command: How to Install MCP Servers in Claude Code
• Claude MCP: How to Configure MCP Servers in Claude Code and Claude Desktop
• Build a Remote Code Execution MCP Server with Novita Sandbox and mcp-use Library