How to Integrate Custom Tools with Anthropic's Plugin Architecture

To integrate custom tools with Anthropic's plugin architecture, define your tool as an MCP server entry in .mcp.json using stdio, http, or sse transport types, then expose it to Claude through a skill that references the tool with the pattern mcp__PLUGIN_NAME_SERVER__TOOL_NAME in the allowed-tools array.

The anthropics/knowledge-work-plugins repository provides a framework for extending Claude's capabilities through self-contained plugins. To integrate custom tools—whether local scripts, REST APIs, or streaming services—developers must configure Model Context Protocol (MCP) servers and wire them into the plugin's skill system. This guide explains how to expose any custom utility as a first-class tool within Anthropic's plugin architecture.

Understanding the Anthropic Plugin Structure

Each plugin in the anthropics/knowledge-work-plugins ecosystem is a self-contained directory with a specific layout. At the root, .claude-plugin/plugin.json serves as the manifest containing the plugin name, version, and description. The skills/ directory houses YAML-frontmatter files that define conversational capabilities, while optional agents/ and hooks/ directories provide additional automation layers.

The .mcp.json file is the critical integration point for custom tools. This configuration file lists all MCP servers—local processes or remote endpoints—that the plugin can access. According to the plugin architecture documentation in cowork-plugin-management/skills/create-cowork-plugin/SKILL.md, this structure enables Claude to discover and invoke external capabilities through a standardized protocol.

Defining Custom Tools in .mcp.json

The .mcp.json file uses a top-level mcpServers object where each key represents a unique tool integration. Three transport types are supported, as defined in the component schemas at cowork-plugin-management/skills/create-cowork-plugin/references/component-schemas.md.

stdio Servers for Local Processes

Use the stdio type for local scripts or binaries that Claude starts and communicates with via standard input/output. This is ideal for Node.js, Python, or compiled tools running on the same machine.

{
  "mcpServers": {
    "my-tool": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/my-tool/server.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

The ${CLAUDE_PLUGIN_ROOT} placeholder resolves to the plugin's installation directory, ensuring relative paths work regardless of where the user installs the plugin. Environment variables can be injected using the ${VAR_NAME} syntax, allowing users to configure secrets without modifying the code. This pattern is demonstrated in the PDF viewer plugin's configuration at pdf-viewer/.mcp.json.

http and sse Servers for Remote Endpoints

For external APIs or streaming services, use http or sse transport types. The http type connects to standard REST endpoints, while sse establishes Server-Sent Events connections for real-time data streams.

{
  "mcpServers": {
    "my-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

Exposing Tools to Claude via Skills

After defining the MCP server, you must expose the tool to Claude through a skill definition. Skills are markdown files in the skills/ directory with YAML frontmatter specifying which tools they can invoke.

The tool reference pattern follows the format: mcp__PLUGIN_NAME_SERVER__TOOL_NAME. For example, if your plugin is named "my-plugin" and your MCP server is "my-tool" with a tool called "analyze", the reference is mcp__my-plugin_my-tool__analyze.

---
description: Run the custom analysis tool
allowed-tools: ["mcp__my-plugin_my-tool__analyze"]
---
Use the custom analysis tool to evaluate the supplied data:
mcp__my-plugin_my-tool__analyze ${ARGUMENTS}

The allowed-tools array acts as a capability manifest, restricting which MCP tools the skill can access. This security model ensures Claude only invokes explicitly permitted operations. Refer to the component schemas in cowork-plugin-management/skills/create-cowork-plugin/references/component-schemas.md for complete allowed-tools pattern syntax.

Using Connector Placeholders for Generic Integrations

For plugins designed to work with interchangeable services (e.g., different payment processors or analytics providers), use connector placeholders. Create a CONNECTORS.md file in the plugin root that maps generic categories to specific implementations using the ~~category syntax.

# CONNECTORS.md

## Analysis Service

Plugin files use `~~analysis` as a placeholder for the connected service.

| Category | Placeholder | Example servers |
| -------- | ----------- | --------------- |
| Analysis | `~~analysis`| my-tool, external-api |

Skills then reference the placeholder instead of hardcoded tool names:

Check ~~analysis for the latest metrics.

When a user connects a specific MCP server, the placeholder resolves to the configured implementation. This abstraction layer makes plugins agnostic to concrete service implementations, as documented in the connector schema reference.

Validating and Packaging Your Plugin

Before distribution, validate your plugin configuration using the CLI:

claude plugin validate

This command checks that .claude-plugin/plugin.json exists, .mcp.json parses correctly, and all referenced files are present. Fix any validation errors to ensure compatibility with Claude's plugin loader.

Once validated, package the plugin by zipping the entire directory into a .plugin file. This archive format preserves the directory structure and allows users to install the custom tool integration directly into their Claude environment, as outlined in the packaging phase documentation.

Summary

• Anthropic plugins use .mcp.json to define custom tools as MCP servers with stdio, http, or sse transport types.
• Reference tools in skills using the pattern mcp__PLUGIN_NAME_SERVER__TOOL_NAME in the allowed-tools array.
• Use ${CLAUDE_PLUGIN_ROOT} for path resolution and ${ENV_VAR} for secure credential injection in .mcp.json.
• Implement connector placeholders in CONNECTORS.md when building generic integrations that support multiple service providers.
• Validate with claude plugin validate and distribute as .plugin zip archives.

Frequently Asked Questions

What file formats does Anthropic's plugin architecture support for custom tools?

The architecture supports three transport protocols defined in .mcp.json: stdio for local processes that communicate via standard input/output, http for standard REST API endpoints, and sse for Server-Sent Events streaming connections. Each entry in the mcpServers object must specify one of these types along with the appropriate connection parameters.

How do I securely pass API keys to my custom tool?

Store sensitive credentials in environment variables and reference them in .mcp.json using the ${ENV_VAR} syntax. For example, "API_KEY": "${MY_API_KEY}" injects the user's environment variable value at runtime. Never hardcode secrets in the plugin files. Document required variables in README.md so users know what to configure before installation.

Can I use the same custom tool across multiple skills?

Yes. Once defined in .mcp.json, any skill can reference the tool by including the full tool identifier in its allowed-tools array. Multiple skills can invoke the same MCP server with different arguments or contexts, enabling modular reuse of your custom tool integration across different conversational workflows.

What is the difference between skills and MCP servers in Anthropic plugins?

MCP servers define the technical integration points—executable commands, HTTP endpoints, or streaming services—while skills provide the conversational interface that determines when and how Claude invokes those tools. The .mcp.json file configures the "how" (the technical connection), and the skill files in skills/ define the "when" (the conversational triggers and prompts).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}