How the Tool-Agnostic Approach of MCP Connectors Works in Knowledge-Work Plugins

The tool-agnostic approach uses category placeholders (e.g., ~~CRM), a data-driven .mcp.json configuration, and runtime tool discovery to let skills interact with any MCP-compatible service without requiring code changes.

The anthropics/knowledge-work-plugins repository implements a flexible integration architecture that decouples business logic from specific vendor implementations. This design allows skills to reference generic tool categories rather than hard-coded products, enabling seamless swapping between services like HubSpot, Salesforce, Gmail, or Microsoft 365 without modifying the underlying skill code.

The Three Pillars of Tool-Agnostic Design

Category Placeholders (~~category Syntax)

At the heart of the system lies a placeholder syntax that uses double-tilde prefixes to denote generic tool categories. Instead of calling specific APIs directly, skill files reference abstract categories like ~~CRM, ~~calendar, ~~email, or ~~project tracker.

In sales/skills/draft-outreach/SKILL.md, the following pattern appears:

[Draft created – check ~~email]

This ~~email token instructs the runtime to look up the Email category configuration rather than hard-coding a call to Gmail or Microsoft 365. The available categories and their semantics are documented in each plugin's CONNECTORS.md file, such as sales/CONNECTORS.md or product-management/CONNECTORS.md.

Dynamic Server Mapping via .mcp.json

The concrete mapping between abstract categories and physical MCP servers lives in a JSON configuration file named .mcp.json at the plugin root. This file lists available MCP servers and their connection details without embedding this data into skill logic.

An excerpt from sales/.mcp.json demonstrates the structure:

{
  "mcpServers": {
    "hubspot": {
      "type": "http",
      "url": "https://mcp.hubspot.com/anthropic"
    },
    "close": {
      "type": "http",
      "url": "https://mcp.close.com/mcp"
    },
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp"
    },
    "ms365": {
      "type": "http",
      "url": "https://microsoft365.mcp.claude.com/mcp"
    }
  }
}

When Claude encounters ~~CRM, it queries this configuration to locate available servers (e.g., HubSpot or Close), then calls the server's tools/list endpoint to discover exact tool names like hubspot.contacts.list. Because this mapping is purely data-driven, replacing HubSpot with Salesforce requires only updating .mcp.json; the skill files remain untouched.

Runtime Tool Discovery and Graceful Degradation

At execution time, the system performs dynamic capability discovery to determine which tools are actually available. The MCP server returns a list of supported tools for the requested category, and the skill adapts its behavior accordingly.

The resolution logic follows this pattern:

def resolve_connector(category):
    server_cfg = mcp_json["mcpServers"].get(category.lower())
    if not server_cfg:
        return None                # no server configured

    tools = request(f"{server_cfg['url']}/tools/list")
    return tools[0] if tools else None

# Usage within a skill execution

email_tool = resolve_connector("email")
if email_tool:
    call_mcp(email_tool, "draft.create", payload)
else:
    # Fallback to manual alternative

    output("Here's a draft you can copy-paste.")

If the server is unavailable or the specific tool is missing, the skill gracefully degrades to static alternatives such as CSV uploads, manual input prompts, or alternative connected categories. This pattern appears throughout the repository, including in partner-built/common-room/CONNECTORS.md, ensuring skills function even without live connectors while automatically upgrading to live data when connections become available.

Implementation Benefits

This architecture delivers several technical advantages:

• Vendor Neutrality: Skills are written once against generic categories and execute against any MCP-compatible product that implements the category interface.
• ** Zero-DCode Modifications**: Adding new services requires only extending .mcp.json or deploying a new MCP server, with no changes to skill logic.
• Parallel Execution: Connectors are batched and requested concurrently, allowing skills that need data from multiple categories (e.g., CRM + calendar + email) to fetch everything simultaneously.
• Consistent User Experience: Users interact with the same commands regardless of underlying tools; Claude reports which connectors were used in the output's "Sources" section.

Summary

• Placeholder syntax (~~category) in skill files abstracts specific vendor APIs into generic business concepts.
• .mcp.json provides a centralized, data-driven mapping between categories and concrete MCP server endpoints.
• Runtime discovery via the tools/list endpoint allows dynamic capability detection without hard-coding tool schemas.
• Graceful degradation ensures skills remain functional when connectors are missing, falling back to manual workflows or static data.
• The design appears consistently across the repository in files like sales/CONNECTORS.md, sales/.mcp.json, and sales/skills/draft-outreach/SKILL.md.

Frequently Asked Questions

What happens if an MCP server is unavailable at runtime?

If the server defined in .mcp.json is unreachable or returns no tools from the tools/list endpoint, the skill automatically falls back to alternative workflows. According to patterns in sales/CONNECTORS.md and related files, this typically means offering CSV uploads, manual input forms, or plain-text drafts that users can copy-paste, ensuring the skill remains usable without live data connections.

How do I add a new CRM connector to an existing skill?

You only need to modify the .mcp.json file at the plugin root. Add a new entry under mcpServers with the server's type and URL (e.g., salesforce pointing to its MCP endpoint). The existing skill code referencing ~~CRM will automatically discover and utilize the new server without requiring any changes to the skill files themselves.

What is the purpose of the ~~ prefix in skill files?

The double-tilde syntax identifies category placeholders that trigger the MCP resolution system. When Claude parses a skill file like sales/skills/draft-outreach/SKILL.md and encounters ~~email, it recognizes this as a signal to look up the Email category in .mcp.json rather than treating the text as a literal string or static command.

Where are the available tool categories documented?

Each plugin maintains a CONNECTORS.md file (e.g., sales/CONNECTORS.md or product-management/CONNECTORS.md) that lists the supported placeholder categories, describes what each category represents, specifies which MCP servers can fulfill it, and documents the fallback behavior when no connector is available.

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