# How to Configure MCP Servers for a Plugin in Knowledge Work Plugins

> Learn to configure MCP servers for your knowledge work plugins. Define HTTP endpoints or CLI commands in your .mcp.json file for seamless integration.

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

---

**To configure MCP servers for a plugin, create or edit a [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file at the root of the plugin directory and define entries under `mcpServers` that map category placeholders to either HTTP endpoints or local CLI commands.**

The `anthropics/knowledge-work-plugins` repository uses the **Model Context Protocol (MCP)** to connect skills with external tools and data sources. Each plugin declares its MCP server dependencies through a dedicated configuration file that the runtime reads to establish connections when placeholders like `~~crm` or `~~slack` appear in skill files.

## Understanding the .mcp.json Configuration Structure

Every plugin maintains its own [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file at its root directory. This file contains a top-level `mcpServers` object that associates logical category names with concrete server implementations.

The configuration supports two primary server types:

- **`http`** – For remote MCP servers accessible via URL
- **`command`** – For locally-executed MCP servers that run as subprocesses

### Core Configuration Elements

Each entry under `mcpServers` requires specific fields depending on the server type:

- **`type`** – Specifies `"http"` for remote connections; omitted or implied when using `command` and `args` for local execution
- **`url`** – The HTTP endpoint for remote MCP servers (required when `type` is `"http"`)
- **`command` / `args`** – The executable and arguments for local servers (e.g., `npx` with package name)
- **`headers`** – Optional key-value pairs for HTTP headers; supports environment variable interpolation using `${VAR_NAME}` syntax
- **`oauth`** – For services requiring interactive authentication, contains `clientId` and `callbackPort` fields

## Configuration Patterns and Examples

### Remote HTTP MCP Servers

For SaaS integrations like CRM or communication platforms, define an HTTP-based MCP server in your plugin's [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file.

```json
{
  "mcpServers": {
    "hubspot": {
      "type": "http",
      "url": "https://mcp.hubspot.com/anthropic"
    }
  }
}

```

*Source:* [[`sales/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/.mcp.json)](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/.mcp.json)

When a skill references `~~hubspot`, the runtime connects to this endpoint.

### Local Command-Based MCP Servers

Plugins that process files locally, such as PDF viewers, spawn MCP servers as child processes using the `command` and `args` fields.

```json
{
  "mcpServers": {
    "pdf": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-pdf", "--stdio"]
    }
  }
}

```

*Source:* [[`pdf-viewer/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/pdf-viewer/.mcp.json)](https://github.com/anthropics/knowledge-work-plugins/blob/main/pdf-viewer/.mcp.json)

This configuration launches the PDF processing server via `npx` when the `~~pdf` placeholder is encountered.

### OAuth-Enabled Services

Services requiring user authorization, such as Slack, include an `oauth` block that triggers a temporary browser-based flow.

```json
{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "clientId": "1601185624273.8899143856786",
        "callbackPort": 3118
      }
    }
  }
}

```

*Source:* [[`sales/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/.mcp.json)](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/.mcp.json)

The runtime opens a browser window on the specified `callbackPort` to complete the OAuth handshake before establishing the MCP connection.

### Environment Variable Substitution

Never hardcode authentication tokens. Use `${VAR_NAME}` syntax in the `headers` object to inject secrets from the process environment.

```json
{
  "mcpServers": {
    "zoom-mcp": {
      "type": "http",
      "url": "https://mcp-us.zoom.us/mcp/zoom/streamable",
      "headers": {
        "Authorization": "Bearer ${ZOOM_MCP_ACCESS_TOKEN}"
      }
    }
  }
}

```

*Source:* [[`partner-built/zoom-plugin/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/zoom-plugin/.mcp.json)](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/zoom-plugin/.mcp.json)

The runtime substitutes the `${ZOOM_MCP_ACCESS_TOKEN}` placeholder with the actual environment variable value at execution time.

## Placeholder Resolution and Skill Integration

The connection between skills and MCP servers relies on **category placeholders** embedded in skill files. When a skill contains a reference like `~~crm` or `~~slack`, the plugin loader performs a lookup in the corresponding [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file.

The category name in the JSON key must exactly match the placeholder used in the skill (minus the `~~` prefix). If no matching entry exists, the skill operates in stand-alone mode, falling back to web search or user-provided data without MCP functionality.

Each plugin maintains complete independence; configurations in [`sales/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/.mcp.json) do not affect [`pdf-viewer/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/pdf-viewer/.mcp.json). For documentation purposes, plugins often include a [`CONNECTORS.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/CONNECTORS.md) file listing available categories and their corresponding MCP tools.

## Summary

- **One file per plugin**: Place [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) at the root of each plugin directory to define its MCP server dependencies.
- **Match placeholders exactly**: The keys under `mcpServers` must correspond to the placeholders used in skill files (e.g., `hubspot` matches `~~hubspot`).
- **Choose the right type**: Use `"http"` for remote services and `command`/`args` for local executables like PDF processors.
- **Secure credentials**: Always use `${ENV_VAR}` syntax in headers instead of hardcoding tokens.
- **Handle OAuth interactively**: Include `oauth` configuration with `clientId` and `callbackPort` for services requiring browser-based authentication.

## Frequently Asked Questions

### Where do I place the .mcp.json file in my plugin directory?

Create the [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file at the root of your plugin directory, alongside your skill files. For example, if you are building a sales plugin, the file belongs at [`sales/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/.mcp.json). The plugin loader automatically detects this file when the plugin initializes.

### How do I reference environment variables in MCP server configuration?

Use the `${VARIABLE_NAME}` syntax within string values in your [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file, typically in the `headers` object for authentication tokens. The runtime replaces these placeholders with values from the current process environment before establishing the connection, keeping secrets out of version control.

### Can multiple plugins share the same MCP server configuration?

No, each plugin maintains its own isolated [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file. The `sales` plugin cannot access MCP servers defined in [`pdf-viewer/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/pdf-viewer/.mcp.json), and vice versa. This isolation ensures that plugins remain self-contained and do not create cross-dependencies.

### What happens if a skill references a placeholder not defined in .mcp.json?

If a skill uses a placeholder like `~~undefined` and no matching key exists in the plugin's [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file, the skill operates in stand-alone mode. It reverts to alternative data sources such as web search or manual user input rather than connecting to an MCP server.