MCP Plugins Integration — Setting Up Local and Remote MCP Servers

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.

Scroll horizontally→

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

This table scrolls horizontally. Keyboard users can focus the table and use the left and right arrow keys.

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

Scroll horizontally→

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://...)

This table scrolls horizontally. Keyboard users can focus the table and use the left and right arrow keys.

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

This article is a general information summary and is not legal advice. Confirm practical decisions with a qualified specialist.

---

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

1. Anthropic, Claude Code documentation
2. Anthropic, Claude API documentation

For the latest releases and updates, check the official website and official documentation.