# How to Integrate Custom Tools with Anthropic's Plugin Architecture

> Easily integrate custom tools with Anthropic's plugin architecture. Learn to define your tool in mcp.json and expose it to Claude using allowed-tools for seamless integration.

- Repository: [Anthropic/knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins)
- Tags: how-to-guide
- Published: 2026-05-25

---

**To integrate custom tools with Anthropic's plugin architecture, define your tool as an MCP server entry in [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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.

```json
{
  "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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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.

```json
{
  "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`.

```markdown
---
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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/CONNECTORS.md) file in the plugin root that maps generic categories to specific implementations using the `~~category` syntax.

```markdown

# 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:

```markdown
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:

```bash
claude plugin validate

```

This command checks that [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) exists, [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json).
- Implement connector placeholders in [`CONNECTORS.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file configures the "how" (the technical connection), and the skill files in `skills/` define the "when" (the conversational triggers and prompts).