Connect tools to Claude Code
Claude Code can connect terminal-based agent sessions to local or remote MCP servers. Scope matters: a project connection is shared through the repository, while a user connection follows you across projects. Prefer the CLI for registration when credentials or user-level settings are involved, and inspect a repository’s MCP file before trusting its processes.
Configuration location
Config file · Project scope: .mcp.json at the repository root
The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details.
1. Choose the scope explicitly
Use project scope only for settings appropriate to share with repository collaborators. Use the CLI’s user scope for a private connection you want in multiple projects. Review all commands and endpoint hosts before registration, including any arguments copied from a README.
2. Register the connection
For a local server, the CLI shape is claude mcp add --transport stdio <name> -- <command> <args>. For a Streamable HTTP server, use claude mcp add --transport http <name> <url>. Replace angle-bracket placeholders with documented values. Add --scope project when you intentionally want a project entry.
3. Inspect status and authentication
Use claude mcp list to inspect registered servers and /mcp inside a Claude Code session to review connection state. Complete authentication only for a trusted service. If you edit .mcp.json directly, keep the mcpServers wrapper and merge rather than replacing unrelated entries.
4. Run a bounded tool call
Start with a read-only request against a test resource. Review the tool’s permission request and arguments before approval. Keep secret tokens out of the shared project file, and use the provider’s documented environment or authentication mechanism instead.
Configuration example
{
"mcpServers": {
"playwright": {
"type": "stdio",
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}This example launches a browser server via npx. Review the package and its current README before running it. Merge the named entry into your existing configuration, and do not commit secrets. Examples demonstrate the file format; they do not bypass a client’s trust or approval prompts.
Playwright MCP installation and toolsTroubleshooting
Check the selected scope, runtime, and working directory if a local server fails. For remote endpoints, distinguish http from legacy sse and use the documented transport. CLI flags and managed configuration can change; check the client documentation before relying on an unfamiliar option.
Client versions and menus change. When the installed version differs from this guide, prefer its current documentation.
