Skip to content
Get packs

Guide · Agent skill

How to use the MCP Integration Guide agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The mcp-integration skill is a set of guidance and templates that teaches an AI agent how to connect a Claude Code plugin to an outside service through the Model Context Protocol (MCP). It is written for plugin developers who want to bundle a service such as Asana or a database with their plugin, and for anyone choosing between stdio, SSE, HTTP and WebSocket server types for the first time. After reading this guide you will know how to install the skill, ask for it in natural language, and check the configuration it produces. The skill is documentation and examples. It does not connect to any service on its own, so you still need the service's own access details, such as API keys or an OAuth account.

MCP Integration Guideanthropics/claude-plugins-official · Apache-2.0

Quick start

  1. 1Download and unzip. Download the ZIP from this page and unzip the mcp-integration folder.
  2. 2Place the skill. Put the folder in ~/.claude/skills/ for personal use or in your project's .claude/skills/ folder, or upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
  3. 3Make a plugin-ready request. Describe the service you want to connect and the plugin it belongs to, for example asking to add an MCP server to your plugin.
  4. 4Pick a server type. Choose stdio for local processes, SSE or HTTP for hosted services, or WebSocket for real-time connections.
  5. 5Reference secrets through environment variables. Use ${VAR_NAME} placeholders for tokens and document them in your plugin README.
  6. 6Pre-allow specific tools. List only the mcp__plugin_... tools each command needs in allowed-tools, then restart Claude Code and check /mcp.

What the skill makes the agent do

Once installed, the agent knows how to write an MCP configuration for a Claude Code plugin. The configuration lives either in a dedicated .mcp.json file at the plugin root or inline in the mcpServers field of plugin.json. The skill also covers how to pass environment variables and tokens, how MCP tools are named, and how to pre-allow specific tools in command frontmatter.

The guidance covers four server types: stdio for local processes, SSE for hosted servers with OAuth, HTTP for token-authenticated REST-style servers, and WebSocket for real-time connections.

  • Write .mcp.json or plugin.json MCP configuration
  • Choose between stdio, SSE, HTTP and WebSocket
  • Reference ${CLAUDE_PLUGIN_ROOT} and user environment variables
  • Explain tool names such as mcp__plugin_<plugin-name>_<server-name>__<tool-name>
  • Pre-allow specific MCP tools in commands

Install the skill from the ZIP

Download the ZIP from this page and unzip it. You can install the skill in either of two places, depending on whether you want it for all your work or only one project.

For a personal install, unzip the folder into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

  • Personal: ~/.claude/skills/
  • Project only: .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Trigger the skill with natural requests

You do not need a special command. The skill's description lists the kinds of requests that should load it, so ask in plain language. Phrases the skill is written to respond to include "add MCP server", "integrate MCP", "configure MCP in plugin", "use .mcp.json", "set up Model Context Protocol" and "connect external service". Mentioning SSE, stdio, HTTP or WebSocket server types also triggers it.

Be specific about your goal. Naming the service and the plugin gives the agent what it needs to produce a usable file.

  • "Set up Model Context Protocol in my plugin so it can read Asana tasks."
  • "Which MCP transport should I use for a local SQLite database: stdio or HTTP?"
  • "Add a .mcp.json to my plugin that starts a local server with an API key from my environment."

Choose a server type

Pick the type that matches where the server runs. The skill describes each type's typical use.

stdio runs a local server as a child process that Claude Code starts and stops with the session. SSE and HTTP connect to hosted servers, with SSE using automatic OAuth and HTTP using a token in a header. WebSocket suits real-time, persistent connections.

  • stdio: local tools, custom servers, NPM-packaged servers
  • SSE: hosted services with OAuth, such as official hosted servers
  • HTTP: REST-style servers using a token in headers
  • WebSocket: real-time streaming and push notifications
{ "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"], "env": { "LOG_LEVEL": "debug" } } }

Pass tokens safely with environment variables

Reference secrets as environment variables instead of writing them into the file. The skill shows values such as "${MY_API_KEY}" that are read from the user's shell. Use ${CLAUDE_PLUGIN_ROOT} for paths inside the plugin so the configuration stays portable. Document every required variable in the plugin's README.

Do not hardcode tokens, commit them to git or paste them into documentation.

  • Use environment variables for tokens
  • Use ${CLAUDE_PLUGIN_ROOT} for paths inside the plugin
  • Document required variables in the README
  • Use HTTPS or WSS URLs, not HTTP or WS
{ "my-server": { "type": "http", "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ${API_TOKEN}" } } }

Pre-allow MCP tools in commands

MCP tools are named as mcp__plugin_<plugin-name>_<server-name>__<tool-name>. For an Asana plugin with an asana server, the create-task tool is mcp__plugin_asana_asana__asana_create_task. List the specific tools a command needs in its allowed-tools frontmatter.

The skill recommends listing specific tools rather than using a wildcard such as mcp__plugin_asana_asana__*, because wildcards grant more access than a command usually needs. Use /mcp to see the servers and tools that are loaded.

  • Pre-allow only the tools a command needs
  • Avoid wildcard permissions
  • Use /mcp to view servers and discover tool names
  • Restart Claude Code after changing configuration
--- allowed-tools: [ "mcp__plugin_asana_asana__asana_create_task", "mcp__plugin_asana_asana__asana_search_tasks" ] ---

Safety notes: scripts and network

The skill runs no scripts and makes no network requests itself. The configurations it helps you write do matter: a stdio server runs a local program on your machine, and SSE, HTTP and WebSocket servers send data to remote services. Review any server command and URL before you enable a plugin, and only connect services you trust.

The guidance mentions error handling for unavailable servers, such as providing fallback behaviour in commands and informing the user. Check the source of any npm package you pass to npx.

  • The skill itself runs no scripts and uses no network
  • Generated stdio configs start local programs you must review
  • Remote servers receive whatever your tools send them
  • Keep API keys out of version control

What people use it for

  • Bundling an Asana-style hosted server with a Claude Code plugin so commands can create and search tasks.
  • Adding a local stdio server that gives an agent access to a project database or file system.
  • Writing a multi-server plugin that connects GitHub and Jira endpoints for one workflow.
  • Creating an autonomous agent that queries a data source through MCP tools and produces a report.
  • Deciding which transport type to use before writing the first .mcp.json file.

Frequently asked questions

How do I install the mcp-integration skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills.

Is the mcp-integration skill free to use?

The source material is licensed under Apache-2.0. Check the licence file in the repository for the full terms before redistributing it.

What do I need to use this skill?

You need Claude Code with its plugin system. The stdio example uses Node.js and npx, and any service you connect may require its own API key or OAuth account.

Does this skill connect to MCP servers for me?

No. It provides guidance and configuration templates, and it does not connect to any service. You still set up the server access details yourself.

What is the difference between stdio, SSE, HTTP and WebSocket?

stdio runs a local server process on your machine. SSE connects to hosted servers with automatic OAuth, HTTP connects to REST-style servers using a token in headers, and WebSocket supports real-time bidirectional connections.

Why isn't my MCP tool showing up?

Restart Claude Code after changing configuration, then run /mcp to see which servers are loaded. Check that the tool name follows the mcp__plugin_<plugin-name>_<server-name>__<tool-name> format.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are building a Claude Code plugin that bundles an external service, or if you are choosing your first MCP transport and want clear templates. Skip it if you only want to use an existing MCP server, since you can configure that directly in Claude Code settings. Avoid relying on its examples for security-sensitive setups without removing any real tokens from files and replacing wildcard tool permissions with specific ones.

Download the skill