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

To configure MCP servers for a plugin, create or edit a .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 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 file.

{
  "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)

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.

{
  "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)

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.

{
  "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)

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.

{
  "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)

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 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 do not affect pdf-viewer/.mcp.json. For documentation purposes, plugins often include a CONNECTORS.md file listing available categories and their corresponding MCP tools.

Summary

• One file per plugin: Place .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 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. 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 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 file. The sales plugin cannot access MCP servers defined in 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 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.

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