Skip to main content
The .mcp.json file configures MCP (Model Context Protocol) server connections for your plugin. It defines which external tools and services Claude can access when your plugin is active.

​
Location

plugin-name/
└── .mcp.json

​
Schema

​
mcpServers
object
required
An object where each key is a unique server identifier and the value is a server configuration object.
{
  "mcpServers": {
    "slack": { ... },
    "notion": { ... }
  }
}

​
Server Configuration

Each server in mcpServers has the following properties:
​
type
string
required
The server transport type. Currently only "http" is supported.
"type": "http"
​
url
string
required
The HTTP endpoint URL for the MCP server. Can be an empty string if the server is not yet configured.
"url": "https://mcp.slack.com/mcp"

"url": ""
Empty URLs are useful for plugins that need user configuration before they can connect to the service.
​
oauth
object
Optional OAuth configuration for servers that require authentication.

​
Examples

​
Basic HTTP Servers

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

​
Server with OAuth

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

​
Servers Requiring Configuration

{
  "mcpServers": {
    "snowflake": {
      "type": "http",
      "url": ""
    },
    "databricks": {
      "type": "http",
      "url": ""
    },
    "bigquery": {
      "type": "http",
      "url": "https://bigquery.googleapis.com/mcp"
    }
  }
}

​
Sales Plugin Example

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp"
    },
    "hubspot": {
      "type": "http",
      "url": "https://mcp.hubspot.com/anthropic"
    },
    "close": {
      "type": "http",
      "url": "https://mcp.close.com/mcp"
    },
    "clay": {
      "type": "http",
      "url": "https://api.clay.com/v3/mcp"
    },
    "zoominfo": {
      "type": "http",
      "url": "https://mcp.zoominfo.com/mcp"
    },
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    },
    "atlassian": {
      "type": "http",
      "url": "https://mcp.atlassian.com/v1/mcp"
    },
    "fireflies": {
      "type": "http",
      "url": "https://api.fireflies.ai/mcp"
    }
  }
}

​
Data Plugin Example

{
  "mcpServers": {
    "snowflake": {
      "type": "http",
      "url": ""
    },
    "databricks": {
      "type": "http",
      "url": ""
    },
    "bigquery": {
      "type": "http",
      "url": "https://bigquery.googleapis.com/mcp"
    },
    "hex": {
      "type": "http",
      "url": "https://app.hex.tech/mcp"
    },
    "amplitude": {
      "type": "http",
      "url": "https://mcp.amplitude.com/mcp"
    },
    "atlassian": {
      "type": "http",
      "url": "https://mcp.atlassian.com/v1/mcp"
    }
  }
}

​
Common MCP Servers

Here are some commonly used MCP server URLs:
ServiceURL
Slackhttps://mcp.slack.com/mcp
Notionhttps://mcp.notion.com/mcp
HubSpothttps://mcp.hubspot.com/anthropic
Linearhttps://mcp.linear.app/mcp
Asanahttps://mcp.asana.com/v2/mcp
Atlassian (Jira)https://mcp.atlassian.com/v1/mcp
Microsoft 365https://microsoft365.mcp.claude.com/mcp
Google Calendarhttps://gcal.mcp.claude.com/mcp
Gmailhttps://gmail.mcp.claude.com/mcp
Figmahttps://mcp.figma.com/mcp
Canvahttps://mcp.canva.com/mcp
Amplitudehttps://mcp.amplitude.com/mcp
BigQueryhttps://bigquery.googleapis.com/mcp
Hexhttps://app.hex.tech/mcp
Mondayhttps://mcp.monday.com/mcp
ClickUphttps://mcp.clickup.com/mcp
Closehttps://mcp.close.com/mcp
Clayhttps://api.clay.com/v3/mcp
ZoomInfohttps://mcp.zoominfo.com/mcp
Fireflieshttps://api.fireflies.ai/mcp
Apollohttps://api.apollo.io/mcp
Outreachhttps://mcp.outreach.io/mcp
SimilarWebhttps://mcp.similarweb.com/mcp
Ahrefshttps://api.ahrefs.com/mcp/mcp
Klaviyohttps://mcp.klaviyo.com/mcp
PubMedhttps://pubmed.mcp.claude.com/mcp
BioRenderhttps://mcp.services.biorender.com/mcp
bioRxivhttps://mcp.deepsense.ai/biorxiv/mcp
ClinicalTrials.govhttps://mcp.deepsense.ai/clinical_trials/mcp
ChEMBLhttps://mcp.deepsense.ai/chembl/mcp
Synapsehttps://mcp.synapse.org/mcp
Wileyhttps://connector.scholargateway.ai/mcp
Owkinhttps://mcp.k.owkin.com/mcp
Open Targetshttps://mcp.platform.opentargets.org/mcp

​
Validation Rules

Required Structure: The top-level mcpServers object is required, even if empty. Each server must have a type and url field.
Empty URLs: You can use an empty string for the url field if the server requires user-specific configuration. This is common for data warehouse connections (Snowflake, Databricks) that need account-specific endpoints.
OAuth Configuration: If you include an oauth object, both clientId and callbackPort are required.

​
Best Practices

  1. Server Names: Use clear, recognizable names for server identifiers (e.g., "slack", "notion", "hubspot").
  2. Empty URLs for Configuration: Use empty URL strings for servers that require user-specific configuration rather than omitting them entirely. This documents which servers the plugin supports.
  3. Organize by Function: Group related servers together in your configuration for better maintainability.
  4. Version Endpoints: Some services include version numbers in their MCP endpoints (e.g., /v1/mcp, /v2/mcp). Use the latest stable version recommended by the service.
  5. OAuth Setup: For servers requiring OAuth, ensure the callbackPort doesn’t conflict with other services in your plugin.
  6. Testing: Verify that all server URLs are accessible and correctly formatted before distributing your plugin.

​
How It Works

When your plugin is activated:
  1. Claude reads the .mcp.json file and establishes connections to all configured servers
  2. Each server exposes tools, resources, and prompts that become available to Claude
  3. Claude automatically uses these tools when relevant to the user’s request
  4. Users may need to authenticate with services (especially those with OAuth) before Claude can access them

Build docs developers (and LLMs) love

Get started for freeTalk to us