Register a custom server with the Claude Code CLI, choose stdio for a local process or SSE/HTTP for a remote service, select a scope, provide credentials safely, and verify it with claude mcp list, claude mcp get, and /mcp. Project-scoped entries live in .mcp.json and require approval, which makes that scope suitable for team tooling.
The quickest working setup
Open a terminal in the project where you use Claude Code. A local MCP server that communicates over standard input/output can be added with:
![Computer Networking Bible: [3 in 1] The Complete Crash Course to Effectively Design, Implement and Manage Networks. Including Sections on Security, Performance and Scalability](https://m.media-amazon.com/images/I/41H4YJnxKgL._SL160_.jpg)
claude mcp add my-server -- python server.py --port 8080The -- separator is important: options before it belong to Claude Code; the command and arguments after it are passed to your server. For a hosted server, use the transport explicitly:
claude mcp add --transport sse my-server https://example.com/sse
claude mcp add --transport http my-server https://example.com/mcpAfter adding it, inspect the registration and then approve or authenticate it in Claude Code:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
claude mcp list
claude mcp get my-serverInside a Claude Code session, run /mcp to view connection status and complete remote OAuth when the service supports it.
Decide how Claude Code will reach the server
| Transport | Use it when | What Claude Code connects to | Operational trade-off |
|---|---|---|---|
| stdio | The server runs on the same machine as Claude Code. | A local executable, script, or package that speaks MCP over standard input/output. | No network endpoint is needed, but Claude must start the process and the executable path must be valid. |
| SSE | The server is hosted remotely and exposes an MCP Server-Sent Events endpoint. | A URL such as https://example.com/sse. |
Requires network reachability and remote authentication where configured. |
| HTTP | The service provides an MCP HTTP endpoint. | A URL such as https://example.com/mcp. |
Shares the remote service’s availability, TLS, and credential requirements. |
Do not select SSE or HTTP merely because a local program uses a web framework. The deciding question is where the MCP endpoint lives and which protocol it exposes.
Choose a configuration scope
| Scope | Command option | Best fit | Visibility and storage |
|---|---|---|---|
| local | --scope local |
Personal experiments or sensitive settings for one project. | Private to you and the current project. |
| project | --scope project |
A tool every contributor should be able to reproduce. | Written to the project’s .mcp.json; suitable for version control after secrets are removed. Project servers require approval before use. |
| user | --scope user |
A personal utility used in several projects. | Private to your account and available across your projects. |
If the same server name is registered at more than one scope, Claude Code resolves local first, then project, then user. Use distinct names when you intentionally need different endpoints or credentials.
Add a local stdio server
- Make the executable reliable. Test the command directly from the project directory. Use an absolute path when the server depends on a virtual environment, a compiled binary, or a runtime that is not on Claude Code’s
PATH. - Register the command and arguments.
claude mcp add --scope project my-server -- /absolute/path/to/server --port 8080Everything after
--is passed unchanged. For a Python script, the equivalent is:Recommended: Update Every Outdated Driver on Your PC in One Scan - Free →Recommended: Fix Windows Errors and Clear Junk Files in Minutes - Free Scan →Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.claude mcp add my-server -- python server.py --port 8080 - Supply process environment variables. Put each
--envoption before the separator:
claude mcp add --scope project --env API_KEY=$MY_SERVER_API_KEY my-server -- /absolute/path/to/serverKeep the secret in your shell environment or a local secret manager. Do not paste a live token into a committed project file.
Add a remote SSE or HTTP server
Register an SSE endpoint like this:
claude mcp add --transport sse --scope user my-server https://example.com/sseFor HTTP, change the transport and URL:
claude mcp add --transport http --scope user my-server https://example.com/mcpWhen the service expects a bearer token or another request header, provide it with --header:
claude mcp add --transport http my-server https://example.com/mcp --header "Authorization: Bearer $MCP_TOKEN"Some services use OAuth 2.0 instead of a static header. Add the server first, start Claude Code, run /mcp, and follow the browser login flow. OAuth is supported with both SSE and HTTP transports.
Share a server with a project safely
A project-scoped registration produces an .mcp.json file. A stdio entry has this shape:
{
"mcpServers": {
"my-server": {
"command": "/absolute/path/to/server",
"args": ["--port", "8080"],
"env": {
"API_KEY": "${MY_SERVER_API_KEY}"
}
}
}
}For a remote service, use a type and url, adding headers when required. Claude Code expands ${VAR} and ${VAR:-default} in commands, arguments, environment values, URLs, and headers. If a referenced variable has neither a value nor a default, parsing fails. Commit the configuration only after checking that it contains variable references rather than credentials.
When a teammate opens a project containing .mcp.json, Claude Code asks for approval before enabling its servers. Review the command, URL, arguments, headers, and capabilities before accepting; approval is a protection against silently granting a project tool access to your data.
Verify, inspect, and remove registrations
Use the CLI to distinguish registration problems from runtime problems:
claude mcp listshows the servers Claude Code knows about.claude mcp get <name>displays one server’s resolved configuration.claude mcp remove <name>removes a registration./mcpinside Claude Code shows connection and authentication controls for the current session.
A name appearing in claude mcp list proves only that the configuration was parsed. A successful connection in /mcp confirms that the process started or the remote endpoint answered and that authentication, if any, completed.
Credentials and least-privilege design
Environment variables for local processes
Use --env KEY=value for values the process reads from its environment, and prefer a reference such as ${MY_SERVER_API_KEY} in a project file. Give the token only the API permissions the MCP tools need.
Headers for remote APIs
Use --header for bearer tokens or vendor-specific headers. Avoid putting secrets directly in shell history; export the value first and interpolate it, or use a local uncommitted configuration.
OAuth for interactive services
Use /mcp to launch the provider’s browser authentication flow. Treat the resulting account access as seriously as a token: a server can read data or perform actions with the authority you grant it.
Troubleshoot common failures
“Connection closed” immediately after adding a server
For stdio, run the exact command outside Claude Code and check its executable path, runtime, working directory, and required environment variables. On native Windows, wrap an npx-based server with cmd /c:
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchclaude mcp add my-server -- cmd /c npx -y <package>This wrapper avoids the documented Windows connection-closed failure for that launch pattern.
The server is listed but never becomes ready
Increase Claude Code’s startup window for a slow process by setting the timeout in milliseconds:
MCP_TIMEOUT=10000 claudeAlso verify that the URL is reachable from the machine running Claude Code, that TLS inspection or a firewall is not blocking it, and that the selected transport matches the endpoint.
“Server not found” or the wrong server is used
Check the spelling and scope with claude mcp list and claude mcp get <name>. A same-named local entry overrides project and user entries. Rename one of the entries or remove the unintended higher-priority registration.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Authentication fails
For headers, inspect the resolved value without exposing the secret in logs and confirm the required prefix, such as Bearer. For OAuth, run /mcp and complete the browser flow. For project configuration, confirm every referenced variable exists; an unset variable without a default causes parsing failure.
Claude warns about an oversized tool response
Claude Code warns when an MCP tool response exceeds 10,000 tokens. If the tool genuinely needs to return more, raise the limit with MAX_MCP_OUTPUT_TOKENS; otherwise change the server to paginate, filter, or summarize results before returning them.
Project server never starts because approval is pending
Open /mcp, inspect the proposed command or URL and requested capabilities, and approve it only if the source and permissions are trusted. Approval is separate from merely committing .mcp.json.
Reliability and performance choices
- Startup: A long-running local runtime adds launch latency; an absolute executable path and a tested environment reduce failures.
- Network: Remote SSE and HTTP depend on DNS, TLS, firewall rules, provider uptime, and token validity. Keep a local fallback when an operation must work offline.
- Output size: Return only the fields an agent needs. Large unfiltered responses consume context and can trigger the 10,000-token warning.
- Scope: Use local while experimenting, project for a reviewed team dependency, and user for a personal cross-project utility.
- Change control: Treat server upgrades, command arguments, and URL changes as configuration changes. Re-run
claude mcp getand test a representative tool after each change.
Security checklist for third-party MCP servers
Anthropic says it has not verified the correctness or security of every third-party MCP server. Untrusted content can also expose users to prompt injection. Before enabling a server:
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →- Review its source, publisher, requested tools, and network destinations.
- Grant a narrowly scoped credential instead of a broad production token.
- Keep secrets out of committed
.mcp.jsonfiles and shell transcripts. - Use project approval for shared configurations and re-check changes during code review.
- Assume that tools can read or modify any resource allowed by their credentials.
Using the same server from the Agent SDK
If the integration must run inside a programmatic agent rather than the interactive CLI, the current Claude Code Agent SDK accepts MCP definitions such as:
mcpServers: {
playwright: {
command: "npx",
args: ["@playwright/mcp@latest"]
}
}You can allow-list tools with names such as mcp__playwright__*. This is useful when your application, rather than a person at a terminal, should control which MCP tools are available.
Or skip the browser setup
If the custom MCP workflow is being built to capture website screenshots, you can call ScreenshotNeo directly instead of maintaining a browser process. ScreenshotNeo is a website screenshot API and MCP server for developers; its clean-shot flow accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and each response reports the result in X-Page-Verdict and X-Billed headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
One request returns an image or PDF. See the ScreenshotNeo API documentation for all options:
Free tools Windows power users keep installed
One-click scans. No signup required.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Every plan includes the feature set: full-page lazy-image loading, CSS-selector element capture, dark mode, device presets and custom viewports, retina scale, PDF controls, custom CSS and JavaScript, click and wait actions, request blocking, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, configurable-TTL caching, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage API, OpenAPI specification, and compatibility with parameter names used by other screenshot APIs.
Best Value
- Used Book in Good Condition
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; yearly billing provides two months free. Create a free ScreenshotNeo account to start.
FAQ
Can I register two transports for one service?
Yes, give each registration a different name, such as service-sse and service-http. This lets you test a migration without changing the existing entry and makes scope resolution unambiguous.
What should a team review when updating .mcp.json?
Review command paths, package versions, URLs, headers, environment-variable names, and the tools the server exposes. Confirm that no literal credential or unnecessary capability was added before merging the change.
Does Claude Code itself run a remote server?
No. Claude Code launches a local stdio process or connects to the remote SSE/HTTP endpoint you register. Availability and authorization of a hosted service remain the provider’s responsibility.
Frequently Asked Questions
Can I register two transports for one service?
Yes. Use different server names for the SSE and HTTP registrations so you can test one without replacing the other.
What should a team review when updating .mcp.json?
Check commands, package versions, URLs, headers, variable references, and exposed tools; reject literal credentials and unnecessary permissions.
Does Claude Code host a remote MCP server for me?
No. It starts local stdio processes or connects to the remote SSE/HTTP endpoint you configure.
Recommended Free Tools
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
