How to Configure a Custom MCP Server in Claude Code

Register a custom MCP server with the Claude Code CLI, choose the transport that matches where it runs, select a scope, provide credentials safely, and then verify the connection. A local process normally uses stdio; a hosted service uses SSE or HTTP.

The shortest working examples are:

# Local stdio process
claude mcp add my-server -- python server.py --port 8080

# Remote SSE endpoint
claude mcp add --transport sse my-server https://example.com/sse

# Remote HTTP endpoint
claude mcp add --transport http my-server https://example.com/mcp

The -- token separates Claude Code options from the command and arguments passed to a local server. Put options such as --env before that separator.

#	Preview	Product	Price
1		Pearson Computer Networking, 8E	$32.70	Buy on Amazon
2		Networking All-in-One For Dummies (For Dummies (Computer/Tech))	$28.25	Buy on Amazon
3		Computer Networking Bible: [3 in 1] The Complete Crash Course to Effectively Design, Implement and...	$31.30	Buy on Amazon
4		Computer Networking A Top-Down Approach	$193.32	Buy on Amazon
5		The TCP/IP Guide: A Comprehensive, Illustrated Internet Protocols Reference	$67.09	Buy on Amazon

Choose the transport first

Transport controls how Claude Code reaches your server. Decide this before registering anything.

For stdio, confirm that the executable is installed, callable by the account running Claude Code, and actually speaks MCP over stdio. For SSE or HTTP, confirm the URL, TLS certificate, network route, and authentication requirements before adding it.

#1 Best Overall

Sale

Pearson Computer Networking, 8E

• brand: Pearson
• Computer Networking, 8e

$32.70

Buy on Amazon

Add a local stdio server

1. Make the command reproducible. Prefer an absolute executable path or a command that is available in the same shell environment Claude Code uses.
2. Register the process.

   claude mcp add my-server -- python server.py --port 8080

3. Pass environment variables before --.

   claude mcp add my-server --env API_KEY=YOUR_API_KEY -- python server.py --port 8080

4. Inspect the saved entry.

   claude mcp get my-server

Everything after -- is passed to the server. If your server needs several arguments, keep them after the separator in their intended order. Do not put a server argument before --, where Claude Code may interpret it as a CLI option.

Use an absolute path when startup depends on the working directory

A relative script path can work from one terminal and fail when Claude Code starts it from another directory. Use a path such as /absolute/path/to/server, or make the command self-contained with its interpreter and arguments.

Add a remote SSE or HTTP server

SSE

claude mcp add --transport sse my-server https://example.com/sse

HTTP

claude mcp add --transport http my-server https://example.com/mcp

Use the transport the service documents; do not assume an HTTP endpoint accepts SSE semantics or vice versa. If the service requires a bearer token or API key in a request header, add it with --header:

claude mcp add --transport http my-server 
  --header "Authorization: Bearer YOUR_TOKEN" 
  https://example.com/mcp

For OAuth-protected remote servers, add the server first, then run /mcp inside Claude Code and follow the browser login flow. OAuth is supported with SSE and HTTP transports.

Pick the right configuration scope

Scope controls who can see the registration and whether it can be shared with a project.

When the same server name exists at multiple scopes, Claude Code resolves local before project, then user. A local registration can therefore override a team-provided project entry with the same name.

Rank #2

Sale

Networking All-in-One For Dummies (For Dummies (Computer/Tech))

$28.25

Buy on Amazon

Choose the scope deliberately: use local while experimenting, project for a reviewed team dependency, and user for a personal service that should not enter a repository.

Create a shareable .mcp.json

A project-scoped stdio definition looks like this:

{
  "mcpServers": {
    "my-server": {
      "command": "/absolute/path/to/server",
      "args": ["--port", "8080"],
      "env": {
        "API_KEY": "${MY_SERVER_API_KEY}"
      }
    }
  }
}

Remote entries use a type and url, with optional headers. Claude Code expands ${VAR} and ${VAR:-default} in command, arguments, environment values, URLs, and headers.

Variable expansion rules

• ${VAR} requires a value. If the variable is missing and has no default, parsing fails.
• ${VAR:-default} uses the supplied default when the variable is unset.
• Keep tokens in the shell environment or an uncommitted local configuration. Never commit live credentials to .mcp.json.

Before committing a project file, review every command, argument, URL, header, and environment value. A project file is configuration for everyone who approves and runs it, not merely a shortcut for your own machine.

Authenticate without leaking secrets

Environment variables for local processes

Use --env KEY=value for a process that reads credentials from its environment. In a project file, reference a variable instead of writing its value directly.

Request headers for remote services

Use --header for a remote API that expects an authorization header:

claude mcp add --transport sse my-server 
  --header "Authorization: Bearer ${MCP_TOKEN}" 
  https://example.com/sse

Ensure the variable is defined in the shell that launches Claude Code. Treat headers as secrets: they can grant the MCP server the authority of the account that issued the token.

Rank #3

Sale

Computer Networking Bible: [3 in 1] The Complete Crash Course to Effectively Design, Implement and Manage Networks. Including Sections on Security, Performance and Scalability

$31.30

Buy on Amazon

OAuth for interactive sign-in

For a service that supports OAuth, run /mcp after registration and complete the browser flow. This avoids pasting a long-lived token into a command line, but you should still review the service and the permissions it requests.

Verify, approve, and test the connection

1. List all registrations:

   claude mcp list

2. Display one server’s configuration:

   claude mcp get my-server

3. Open Claude Code’s connection and authentication controls:

   /mcp

4. If the server came from a project .mcp.json, approve it only after reviewing its command, URL, arguments, headers, and requested capabilities.
5. Ask Claude Code to perform a low-risk operation first. Confirm that the expected tool names appear and that the response is complete before granting access to production data or actions.

Remove an entry you no longer trust or need with:

claude mcp remove my-server

Troubleshoot common failures

“Connection closed” on native Windows

When an npx-based server closes immediately on native Windows, wrap it with cmd /c:

claude mcp add my-server -- cmd /c npx -y <package>

The wrapper avoids the documented Windows startup failure for this command shape.

The server does not appear in claude mcp list

• Check that you registered the expected scope; a project entry and a user entry are separate.
• Look for a name collision. A local server with the same name takes precedence over project and user entries.
• Run claude mcp get <name> and verify the exact command or URL.
• If it is project-scoped, check whether approval is still pending.

Executable or script not found

Use an absolute path, verify the interpreter is installed for the same account, and test the command independently in the shell where you launch Claude Code. A server that works only because of an interactive shell profile may not start with the same environment.

Remote URL cannot be reached

Check DNS, firewall and proxy rules, TLS certificates, and whether you selected the service’s actual SSE or HTTP endpoint. Confirm that required headers are present and that the token has not expired.

Missing environment variable or parse error

Define every variable referenced by ${VAR}, or provide a default using ${VAR:-default}. Inspect the project file for malformed JSON and shell quoting errors.

Rank #4

Computer Networking A Top-Down Approach

$193.32

Buy on Amazon

Startup takes too long

Increase Claude Code’s startup window by setting MCP_TIMEOUT in milliseconds:

MCP_TIMEOUT=10000 claude

Use a larger value only when the server genuinely needs more time; slow startup can also indicate a missing dependency, network retry, or an executable that is waiting for interactive input.

Tool output is truncated or triggers a warning

Claude Code warns when an MCP tool response exceeds 10,000 tokens. If that output is intentional, raise the limit with MAX_MCP_OUTPUT_TOKENS; otherwise change the tool to return a focused result, pagination, or a file reference instead of an unbounded payload.

Operational and security practices

Limit authority

An MCP server can read data or perform actions with the authority granted to it. Start with the smallest useful credentials, narrow API scopes, and a non-production account when possible. Review tool names and arguments before approving a project server.

Review third-party code

Anthropic has not verified the correctness or security of every third-party MCP server. Install only servers you trust, inspect their source or publisher, and consider what untrusted page or document content could cause prompt injection. Do not give a server credentials it does not need.

Design for reliable startup

• Pin package versions where reproducibility matters, rather than relying on an unbounded latest package.
• Keep startup output on the correct protocol streams; a stdio MCP server must not write arbitrary logs into the protocol stream.
• Use explicit timeouts and bounded responses for remote calls.
• Record which scope, transport, URL, and credential mechanism a team entry expects so another developer can reproduce it.

Use the same server from the Agent SDK

If the integration must run inside a programmatic agent instead of the interactive CLI, the current Claude Code Agent SDK accepts MCP server definitions such as:

Best Value

Sale

The TCP/IP Guide: A Comprehensive, Illustrated Internet Protocols Reference

• Used Book in Good Condition

$67.09

Buy on Amazon

mcpServers: {
  playwright: {
    command: "npx",
    args: ["@playwright/mcp@latest"]
  }
}

You can allow-list tools with names such as mcp__playwright__*. This is useful when an application and a developer’s Claude Code session must use the same external database, browser, or API integration while retaining separate runtime controls.

Or skip the browser setup

If your custom MCP workflow needs website screenshots, ScreenshotNeo provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. It also exposes a one-request screenshot API; the complete parameter reference is in the ScreenshotNeo documentation.

A cURL request:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

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}`);

Before capture, ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and each response reports the result through X-Page-Verdict and X-Billed headers. It supports clean screenshots, PDFs, custom CSS and JavaScript, selectors, device presets, waiting rules, request blocking, authentication headers and cookies, geolocation, signed links, asynchronous jobs, bulk capture, and an MCP server.

The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots; yearly billing provides two months free. Create a free ScreenshotNeo account to get started.

Frequently Asked Questions

Can I keep a personal override while sharing a team server?

Yes. Give both entries the same name only if you intend the local entry to take precedence over the project entry. Use a distinct name when you want both available without ambiguity.

What should a project reviewer check before approving an MCP server?

Review the executable or URL, every argument, header, environment reference, requested tool capability, and the credentials the process will inherit. Reject or edit entries that expose secrets or production authority unnecessarily.

When is the Agent SDK preferable to the CLI registration?

Use the SDK when the MCP connection must be created and controlled inside a programmatic agent. Use the CLI for an interactive Claude Code workspace where scope, approval, and /mcp controls are sufficient.

Quick Recap

SaleBestseller No. 1

Pearson Computer Networking, 8E

brand: Pearson; Computer Networking, 8e

$32.70

SaleBestseller No. 2

Networking All-in-One For Dummies (For Dummies (Computer/Tech))

$28.25

SaleBestseller No. 3

Computer Networking Bible: [3 in 1] The Complete Crash Course to Effectively Design, Implement and Manage Networks. Including Sections on Security, Performance and Scalability

$31.30

Bestseller No. 4

Computer Networking A Top-Down Approach

$193.32

SaleBestseller No. 5

The TCP/IP Guide: A Comprehensive, Illustrated Internet Protocols Reference

Used Book in Good Condition

$67.09

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.