Set up MCP Integration safely in Claude Code plugins

This guide complements Anthropic’s official MCP Integration guidance. It does not replace a security approval or the documentation of the specific MCP server.

Define the goal and data flow

Start by documenting which external service the plugin must reach, which tools are needed, and which data may leave the project boundary. Separate read-only work from actions that change external state. Confirm ownership, retention, logging, and human approval requirements before establishing a connection.

Choose a configuration shape

Use a dedicated .mcp.json when several servers are involved or when connection review should be independent from plugin metadata. Embedding the configuration in plugin.json can remain clear for a small plugin. Local stdio processes need controlled paths and process permissions. Remote services require HTTPS or WSS and an understandable OAuth or environment-variable design. Never place real credentials in files, commits, or examples.

Limit the tools

Review the generated tool names and allow only the functions required by the specific command. Broad access increases the impact of a bug or a manipulated response. Treat responses from external systems as untrusted data, validate inputs, and design a clear fallback for connection failures.

Test and operate

First validate the configuration structure and test connectivity in a non-production environment. Check the server overview, tool discovery, OAuth sign-in, timeout behavior, and diagnostic logs. After configuration changes, restart the plugin runtime when required. Record the transport, version, permissions, data flow, and a safe disable procedure.

FAQ

A common question concerns the choice between stdio and a remote transport. Stdio fits locally controlled processes, while SSE, HTTP, or WebSocket are intended for reachable services. The decision should follow security, operational, and latency requirements.

Another question is whether a token may be placed in plugin configuration. No. Tokens belong in an appropriate secret-management system or environment variables and must not appear in examples or version control.