MCP integration - Knowledge Work Plugins

Knowledge Work Plugins use the Model Context Protocol (MCP) to connect Claude to external tools and services. MCP provides a standardized way for Claude to discover, invoke, and interact with tools across your company’s stack.

What is MCP

The Model Context Protocol is an open standard that enables AI assistants to interact with external data sources and tools through a common interface.

Standardized interface

Tools expose capabilities through a consistent protocol, so Claude doesn’t need custom integration for each service.

Bidirectional communication

Claude can read data from tools (query CRM), write data to tools (update records), or both.

Tool discovery

MCP servers advertise their capabilities, so Claude knows what’s available and how to use it.

Secure authentication

User credentials are managed outside the plugin, with scoped permissions per tool.

MCP architecture

Here’s how MCP connects your plugin to external tools:

┌─────────────────────────────────────────────────────────────────┐
│                         YOUR PLUGIN                              │
│  .mcp.json lists which servers to connect to                    │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      MCP PROTOCOL LAYER                          │
│  - Server discovery                                              │
│  - Tool capability enumeration                                   │
│  - Request/response handling                                     │
│  - Authentication management                                     │
└─────────────────────────────────────────────────────────────────┘
                              ↓
        ┌─────────────┬─────────────┬─────────────┬────────────┐
        ↓             ↓             ↓             ↓            ↓
  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
  │ HubSpot  │  │  Slack   │  │ Fireflies│  │  Notion  │  │   ...    │
  │   MCP    │  │   MCP    │  │   MCP    │  │   MCP    │  │   MCP    │
  │  Server  │  │  Server  │  │  Server  │  │  Server  │  │  Server  │
  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘
       ↓             ↓             ↓             ↓            ↓
  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
  │ HubSpot  │  │  Slack   │  │ Fireflies│  │  Notion  │  │   ...    │
  │   API    │  │   API    │  │   API    │  │   API    │  │   API    │
  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘

MCP server types

MCP servers expose three types of capabilities:

1. Tools

Tools are functions Claude can invoke to perform actions:

{
  "tools": [
    {
      "name": "search_contacts",
      "description": "Search for contacts in HubSpot CRM",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "limit": { "type": "number" }
        }
      }
    },
    {
      "name": "update_deal",
      "description": "Update a deal's properties",
      "inputSchema": {
        "type": "object",
        "properties": {
          "deal_id": { "type": "string" },
          "stage": { "type": "string" },
          "close_date": { "type": "string" }
        }
      }
    }
  ]
}

2. Resources

Resources are data sources Claude can read:

{
  "resources": [
    {
      "uri": "hubspot://contacts/recent",
      "name": "Recent Contacts",
      "mimeType": "application/json"
    },
    {
      "uri": "hubspot://deals/pipeline",
      "name": "Sales Pipeline",
      "mimeType": "application/json"
    }
  ]
}

3. Prompts

Prompts are templates the server provides:

{
  "prompts": [
    {
      "name": "account_summary",
      "description": "Generate account summary from CRM data",
      "arguments": [
        {
          "name": "account_id",
          "description": "HubSpot account ID",
          "required": true
        }
      ]
    }
  ]
}

How plugins use MCP

1. Server configuration

Plugins declare which MCP servers to connect to:

.mcp.json

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

2. Capability discovery

When your plugin loads, Claude:

Connects to each MCP server

Establishes connection using the configured URL

Requests capability list

Asks each server: “What tools, resources, and prompts do you provide?”

Builds tool catalog

Aggregates all available capabilities from all connected servers

Makes tools available to skills

Your plugin’s skills and commands can now reference these tools

3. Tool invocation

When a skill needs to use a tool:

call-prep/SKILL.md

### Step 1: Gather Context

**If connectors available:**

1. CRM → Query account
   - Pull: account details, all contacts, open opportunities

Claude translates this to MCP tool calls:

{
  "server": "hubspot",
  "tool": "search_accounts",
  "arguments": {
    "query": "Acme Corp",
    "include": ["contacts", "deals", "activities"]
  }
}

4. Response handling

The MCP server returns structured data:

{
  "result": {
    "account": {
      "name": "Acme Corp",
      "industry": "Software",
      "employees": 500
    },
    "contacts": [...],
    "deals": [...],
    "recent_activities": [...]
  }
}

Claude uses this data to generate the call prep brief.

Execution flow example

Here’s how MCP works in practice for the call-prep skill:

User request

“Prep me for my call with Acme Corp tomorrow”

Skill activation

The call-prep skill matches this request and activates

Connector detection

Skill checks: Are CRM, email, calendar, Slack connectors available?

MCP tool calls (parallel)

// To HubSpot MCP server
{"tool": "search_accounts", "arguments": {"query": "Acme Corp"}}

// To Google Calendar MCP server
{"tool": "find_meeting", "arguments": {"query": "Acme Corp", "date": "tomorrow"}}

// To Slack MCP server
{"tool": "search_messages", "arguments": {"query": "Acme Corp"}}

Data synthesis

Claude combines responses from all MCP servers with web research

Output generation

Generates call prep brief using the skill’s template and gathered data

Authentication and security

MCP handles authentication outside your plugin:

First-time connection

User installs plugin

Plugin’s .mcp.json lists required MCP servers

Authentication prompt

When Claude first needs a connector, user is prompted to authenticate

OAuth flow

User completes OAuth flow with the service (e.g., HubSpot login)

Token storage

Access tokens are securely stored by Claude, not in your plugin

Subsequent uses

Claude uses stored tokens automatically
Tokens are refreshed transparently
Users can revoke access at any time

Permission scopes

Each MCP server requests specific permissions:

HubSpot MCP server

Requested scopes:

crm.objects.contacts.read
crm.objects.deals.read
crm.objects.deals.write
crm.objects.companies.read

What this allows:

Read account and contact data
Read and update deal information
Cannot delete records
Cannot access settings or admin functions

Slack MCP server

Requested scopes:

search:read
channels:read
chat:write

What this allows:

Search messages in channels user has access to
Read channel list
Post messages
Cannot read private messages without explicit access

Building custom MCP servers

You can create MCP servers for internal tools or services that don’t have one:

Implement MCP protocol

Build an HTTP server that implements the MCP specification

Expose tools

Define the tools your server provides and their input schemas

Handle authentication

Implement OAuth or API key authentication for your service

Add to .mcp.json

Configure your plugin to use your custom server

Example: Custom internal API

.mcp.json

{
  "mcpServers": {
    "internal-crm": {
      "type": "http",
      "url": "https://mcp.yourcompany.com/crm"
    },
    "internal-wiki": {
      "type": "http",
      "url": "https://mcp.yourcompany.com/wiki"
    }
  }
}

See the Adding MCP Servers guide for implementation details.

MCP vs direct API calls

Why use MCP instead of calling APIs directly?

Standardization

MCP: One protocol for all toolsDirect APIs: Custom integration for each service

Authentication

MCP: Centralized auth handled by ClaudeDirect APIs: Manage credentials in plugin code

Discovery

MCP: Claude learns what tools are availableDirect APIs: Hard-code available endpoints

Maintenance

MCP: API changes handled by MCP serverDirect APIs: Update plugin code for every API change

Error handling

MCP provides structured error responses:

{
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Please authenticate with HubSpot to continue"
  }
}

Skills can handle common errors gracefully:

**If CRM connection fails:**

I couldn't connect to your CRM. I'll prep your call using web research instead. 
To get account history next time, connect your CRM in settings.

Testing without connectors

Plugins should work without MCP connections:

Development
Production

Test your plugin with connectors disabled to ensure standalone mode works:

.mcp.json

{
  "mcpServers": {}
}

Skills should gracefully fall back to manual input and web research.

Best practices

Design for graceful degradation

Every skill should have a fallback mode when connectors aren’t available. Never make MCP a hard requirement.

Request minimal permissions

Only request the OAuth scopes your plugin actually needs. Users are more likely to connect tools with limited permissions.

Handle errors gracefully

If an MCP call fails, fall back to alternative approaches or ask the user for manual input.

Document connector benefits

Use connector tables in skills to show users what they gain by connecting each tool.

Test both modes

Validate your plugin works well both with and without each connector enabled.

Learn more

MCP Specification

Official Model Context Protocol specification

MCP Servers

Directory of available MCP servers

Build an MCP Server

Create a custom MCP server for your tools

Connectors

Back to connector overview

Get Started

Core Concepts

Business Plugins

Operations Plugins

Technical Plugins

Specialized Plugins

Customization

Building Plugins

​What is MCP

Standardized interface

Bidirectional communication

Tool discovery

Secure authentication

​MCP architecture

​MCP server types

​1. Tools

​2. Resources

​3. Prompts

​How plugins use MCP

​1. Server configuration

​2. Capability discovery

​3. Tool invocation

​4. Response handling

​Execution flow example

​Authentication and security

​First-time connection

​Subsequent uses

​Permission scopes

​Building custom MCP servers

​Example: Custom internal API

​MCP vs direct API calls

Standardization

Authentication

Discovery

Maintenance

​Error handling

​Testing without connectors

​Best practices

​Learn more

MCP Specification

MCP Servers

Build an MCP Server

Connectors

Build docs developers (and LLMs) love

What is MCP

MCP architecture

MCP server types

1. Tools

2. Resources

3. Prompts

How plugins use MCP

1. Server configuration

2. Capability discovery

3. Tool invocation

4. Response handling

Execution flow example

Authentication and security

First-time connection

Subsequent uses

Permission scopes

Building custom MCP servers

Example: Custom internal API

MCP vs direct API calls

Error handling

Testing without connectors

Best practices

Learn more