MCP Plugins Integration — Setting Up Local and Remote MCP Servers

About 10 minutes

Those who understand the basic structure of settings.json (permissions and hooks) and want to integrate Claude Code's functionality with external tools. It is recommended to read [Settings JSON Design](./settings) first.

Understanding the basic structure of `.claude/settings.json`
Ability to perform basic npm / npx operations
Having obtained an API token for the external service you want to integrate (such as GitHub)

By configuring MCP servers, Claude Code can directly operate external tools such as web search, the GitHub API, and the local filesystem. This page covers in order: the concept of MCP, how to configure in settings.json, and secure management of credentials.

What Is MCP?

MCP (Model Context Protocol) is a standard protocol for Claude to communicate with external tools and data sources. An MCP server operates as a process that receives requests from Claude and bridges the gap to external services.

Without MCP, Claude relies only on text passed during the session to answer. By configuring MCP, Claude can perform actual actions such as “reading and writing files,” “fetching a list of pull requests on GitHub,” and “searching a database.”

The Difference Between Local MCP and Remote MCP

MCP servers come in two types: local MCP that runs on the user’s machine, and remote MCP that connects to a cloud server.

Item	Local MCP	Remote MCP
Execution location	User’s machine	Cloud server
How to start	Start a process with `command`	Connect with `url`
Authentication	Not required (or local configuration only)	API key, OAuth
Use case	Filesystem, local DB	GitHub, Slack, external APIs
Example	`@modelcontextprotocol/server-filesystem`	GitHub MCP server

Local MCP operates without an internet connection, so it is suitable for handling internal files or confidential data. Remote MCP is used when you want to call an external service’s API directly from Claude.

How It Works: How to Configure in settings.json

MCP servers are defined in the mcpServers section of .claude/settings.json.

Basic Structure

{
  "mcpServers": {
    "server-name": {
      "command": "execution command",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "${ENV_VAR}"
      }
    }
  }
}

Description of Configuration Fields

Field	Type	Description
`command`	For local	The command to execute (`npx`, `node`, `python`, etc.)
`args`	For local	Array of arguments passed to `command`
`env`	For local	Environment variables passed to the MCP server process
`url`	For remote	URL of the remote server (`https://...` or `ws://...`)

Configuration Example: GitHub MCP and Filesystem MCP

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects"
      ]
    }
  }
}

Writing ${GITHUB_TOKEN} causes Claude Code to reference the shell’s GITHUB_TOKEN environment variable. Use this format to avoid writing API keys directly into the file.

Best Practices

Pass Credentials as Environment Variable References

If you write API keys directly in settings.json, credentials will be leaked when that file is committed. Reference environment variables in the ${VAR_NAME} format, and place actual values in the shell profile (.zshrc or .bashrc) or in the env section of settings.local.json.

// Setting to avoid: writing the API key directly
"env": {
  "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
}

// Recommended: reference the environment variable
"env": {
  "GITHUB_TOKEN": "${GITHUB_TOKEN}"
}

Place Secrets in settings.local.json

Do not include credentials in the team-shared settings.json. Define personal API keys and experimental MCP servers in settings.local.json. Since settings.local.json is excluded by .gitignore, it is not included in the repository.

Restrict the Access Scope for Filesystem MCP

@modelcontextprotocol/server-filesystem restricts the access scope by specifying paths. Instead of opening the entire home directory unrelated to the project, specify only the directories being worked on.

// Setting to avoid: opening the entire home directory
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname"]

// Recommended: limiting to a specific project directory
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"]

Only Install MCP Servers from Trusted Sources

MCP servers are processes that access external systems on Claude’s behalf. Prefer official @modelcontextprotocol/server-* packages or servers published by well-known providers. Do not install MCP servers of unknown origin.

Delete Unused MCP Servers

MCP servers registered in mcpServers attempt to connect when Claude Code starts up. Leaving unused MCP servers leads to increased startup time, error noise, and an expanded attack surface. Review periodically and delete unnecessary ones.

Hands-on Exercise

Step 1: Check the Current MCP Configuration

Navigate to the project root in the terminal and check the current settings.

cat .claude/settings.json

Read the presence of the mcpServers section and the list of registered servers.

✅ Verify: If the JSON file is displayed, the read was successful. If the mcpServers section is absent, add it in the next step.

Step 2: Add the GitHub MCP Server

Set up the GITHUB_TOKEN environment variable in advance. Issue a token with the repo scope from GitHub’s “Settings > Developer settings > Personal access tokens.”

export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

Then add the following to the mcpServers section of .claude/settings.json.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

✅ Verify: Check that the JSON syntax is correct. Check for trailing commas or bracket mismatches.

Step 3: Restart Claude Code and Check MCP

Exit the Claude Code session once and restart it. Then run the /mcp command in chat.

/mcp

Example output:

Connected MCP servers:
- github (connected)

✅ Verify: If github (connected) is displayed, the connection to the GitHub MCP server was successful. If an error such as failed to connect is displayed, verify that the GITHUB_TOKEN environment variable is correctly set.

Step 4: Verify GitHub MCP Is Working

Ask Claude the following to confirm that GitHub MCP is operating correctly.

Please list the open PRs in this repository.

If Claude retrieves the pull request list through the GitHub API and responds, the MCP integration is successful.

✅ Verify: If Claude returns a list including PR numbers, titles, and creators, the operational verification is complete. If a response like “I don’t have connection information to GitHub” appears, recheck that the /mcp display shows connected in Step 3.

Summary

MCP (Model Context Protocol) is a protocol for Claude to communicate with external tools and data sources
MCP servers come in two types: local (start a process with command) and remote (connect with url)
Configure in the mcpServers section of .claude/settings.json
Reference API keys as environment variables in ${VAR_NAME} format; do not write them directly in the file
Place personal credentials in settings.local.json, separate from the Git-shared settings.json
Regularly delete unnecessary MCP servers to minimize the attack surface

Next Steps

Memory System Design — Learn how to design Memory that retains information across sessions
Harness Testing and Validation — Move on to verifying that the entire configuration including MCP functions as intended

Frequently Asked Questions

Q: Running /mcp displays nothing.

A: Check whether the mcpServers section exists in settings.json and whether the JSON syntax is correct. Also, configuration changes may not be reflected without restarting Claude Code.

Q: Can an MCP server be started with a command other than npx?

A: Yes. Any executable can be specified in the command field, such as node, python, or deno. By passing the script path in args, you can also start a self-made MCP server.

Q: Can local MCP and remote MCP be configured at the same time?

A: Yes. Simply add multiple entries to the mcpServers object. Mixing local MCP (command format) and remote MCP (url format) is also fine.

Q: How does Claude behave if an MCP server fails to start?

A: If the connection to an MCP server fails, Claude operates in normal conversation mode without using that server’s functionality. Check the server status with /mcp and review the configuration of the server experiencing errors.

Q: What is the scope of repositories accessible through GitHub MCP?

A: It depends on the scope granted to the GITHUB_TOKEN and the repositories accessible to the account the token belongs to. To access an organization’s repositories, the org scope or SSO authorization may be required.

See the references for the external specifications and background sources used on this page.[1][2]

References

Anthropic, Claude Code documentation
Anthropic, Claude API documentation

Quiz

Memory System Design — Design Guidelines for User, Project, and Reference Memory

Hooks Implementation — Automate with Lifecycle Hooks