ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Configure a Custom MCP Server in Claude Code

Add local or remote MCP servers to Claude Code, choose the right scope and transport, handle credentials, and fix common connection errors.

By the ScreenshotNeo team1 October 20267 min read

Direct answer: Register a custom MCP server with the Claude Code CLI, choose stdio for a local process or SSE/HTTP for a remote endpoint, select a scope, provide credentials, then verify it with claude mcp list, claude mcp get, and /mcp. The commands below cover the complete setup.

Claude Code’s MCP configuration lets Claude connect to external databases, browsers, APIs, and other tools. Anthropic’s reference documentation is the primary source for the commands and configuration format: Claude Code MCP documentation.

1. Choose the transport

Transport Use it when Connection
stdio Your server runs as a local executable or script Claude Code starts the process and communicates over standard input/output
SSE A hosted MCP service exposes an SSE endpoint Claude Code connects to a remote URL
HTTP A hosted MCP service exposes an HTTP MCP endpoint Claude Code connects to a remote URL

Use local stdio for a server that depends on files, local browsers, or development credentials. Use SSE or HTTP when the service is deployed separately and reachable over the network.

2. Add a local stdio server

Make sure the executable is on your PATH or provide an absolute path. The -- token separates Claude Code options from the command and arguments passed to your server.

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

For a Node-based server:

claude mcp add my-server -- node server.js

For an executable file:

claude mcp add my-server -- /absolute/path/to/server --port 8080

Pass environment variables

Put --env options before --. Keep secrets outside the command history when possible.

claude mcp add my-server --env API_KEY="$MY_SERVER_API_KEY" -- python server.py

You can also pass more than one variable:

claude mcp add my-server \
  --env API_KEY="$MY_SERVER_API_KEY" \
  --env API_URL="https://api.example.com" \
  -- python server.py

3. 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

Remote authentication headers

Supply a bearer token or API key with --header:

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

Remote servers may also use OAuth 2.0. Add the server, run /mcp inside Claude Code, and follow the browser authentication flow. OAuth works with SSE and HTTP transports.

4. Pick the correct configuration scope

Scope Best for Sharing
local Personal experiments or sensitive project work Private to you in the current project
project Tools every contributor needs Stored in the project’s .mcp.json; suitable for version control after reviewing secrets
user A personal utility used in several projects Private to your account across projects

When the same server name exists at multiple scopes, Claude Code resolves local before project, then user. Choose the scope explicitly so a personal override does not silently replace a team configuration.

Use the scope flag when registering a server:

claude mcp add --scope local my-server -- python server.py
claude mcp add --scope project my-server -- python server.py
claude mcp add --scope user my-server -- python server.py

5. Share a project server with .mcp.json

A project-scoped configuration is stored in .mcp.json. A stdio entry 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:

{
  "mcpServers": {
    "remote-server": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      }
    }
  }
}

Claude Code expands ${VAR} and ${VAR:-default} in commands, arguments, environment variables, URLs, and headers. If a required variable has no value and no default, parsing fails.

Project-scoped servers require approval before use. Review the command, URL, arguments, headers, and requested capabilities before accepting the server.

6. Verify the connection

Run these checks after registration:

claude mcp list
claude mcp get my-server

Inside Claude Code, use:

/mcp

The /mcp screen provides connection and authentication controls, including the OAuth flow for supported remote servers. If the server is listed but disconnected, inspect its command, URL, environment, and logs before changing the scope.

7. Configure a screenshot MCP server with ScreenshotNeo

ScreenshotNeo provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. It is useful when an agent needs visual page capture without maintaining a browser process.

Follow the current MCP installation instructions in the ScreenshotNeo documentation, then register the server using the command supplied there. Once connected, the agent can call the screenshot tools from Claude Code like any other MCP server.

8. Troubleshooting

“Connection closed” on Windows

Cause: Native Windows may close an npx-based process when it is not launched through the command shell wrapper.

Fix:

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

The server does not appear in claude mcp list

  • Confirm the server name and command.
  • Check whether it was added to a different scope.
  • Run claude mcp get <name> for the expected scope.
  • Check that the project configuration is in the current project directory.
  • Look for a pending approval request for a project server.

The executable cannot be found

Cause: The command is not on Claude Code’s PATH, or the configured path is relative to a different working directory.

Fix: Use an absolute executable path, activate the required runtime before launching Claude Code, or use an explicit interpreter such as python or node.

Environment variables are empty

Cause: The variable is unset, misspelled, or referenced without a default.

Fix: Export it before starting Claude Code and verify the spelling. Use ${VAR:-default} only for non-secret fallback values. Never commit live tokens to .mcp.json.

A remote server cannot be reached

Cause: The URL, transport, firewall, TLS certificate, or authentication header is wrong.

Fix: Confirm that the endpoint matches its documented transport, test network access from the same machine, check the Authorization header, and retry with /mcp.

The server starts too slowly

Increase Claude Code’s startup timeout in milliseconds:

MCP_TIMEOUT=10000 claude

A tool response is too large

Claude Code warns when an MCP response exceeds 10,000 tokens. Raise the limit only when the tool genuinely needs to return more data:

MAX_MCP_OUTPUT_TOKENS=20000 claude

9. Security checklist

  • Install only MCP servers you trust and inspect their source or publisher.
  • Grant the smallest credentials and capabilities the server needs.
  • Keep API keys in environment variables or an uncommitted local configuration.
  • Review project-scoped server changes before approving them.
  • Remember that untrusted content can contain prompt injection and that a server can read data or perform actions with the authority you grant it.

Anthropic has not verified the correctness or security of every third-party MCP server, so treat each installation as code with access to your development environment.

10. Operational guidance

Performance

  • Local stdio avoids network round trips but includes process startup time.
  • Remote SSE and HTTP avoid local installation but depend on network latency and endpoint availability.
  • Keep tool responses focused; large responses increase parsing time and can hit the output limit.
  • Use a longer startup timeout for servers that load browsers, large models, or dependency graphs.

Reliability

  • Pin executable versions where reproducibility matters.
  • Use absolute paths in shared configurations when the team standardizes its environment.
  • Keep remote endpoints stable and document required headers and OAuth setup.
  • Give team members a short verification procedure using claude mcp list, claude mcp get, and /mcp.

Cost

Claude Code’s MCP configuration itself does not define a universal service price. Any hosted MCP provider may charge separately, and local servers consume your own machine resources. Check the provider’s terms before sharing a remote endpoint or using it in automation.

11. Do-it-yourself versus a hosted screenshot API

Running a browser MCP server yourself gives you control over the runtime, browser version, network, and credentials. It also means maintaining browser dependencies, handling cookie banners and overlays, and diagnosing failed page loads.

Or skip the browser setup

ScreenshotNeo returns a screenshot or PDF from one GET request. It accepts the cookie or consent banner like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture. Each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the result with X-Page-Verdict and X-Billed headers.

cURL

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

ScreenshotNeo also supports full-page capture with lazy images loaded, CSS element capture, dark mode, device presets, custom viewports, retina scale, PDFs, custom CSS and JavaScript, clicks, hidden selectors, selector or network-idle waits, request blocking, custom headers and cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, configurable caching, signed links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. Parameter names used by other screenshot APIs also work, which can simplify migration.

There is a free plan with 1,000 screenshots per month and no card. Paid plans start at $5 for 3,000 screenshots; yearly billing provides two months free, and every feature is available on every plan.

Create a free ScreenshotNeo account and start with 1,000 screenshots a month at no charge.

12. FAQ

Can one MCP server be available in every project?

Yes. Register it with user scope. It remains private to your account and is available across projects.

Should a team commit .mcp.json?

Project scope is designed for team sharing. Review commands, URLs, headers, and environment references first, and do not commit live secrets.

Can Claude Code use OAuth with a local stdio server?

The documented OAuth flow applies to remote SSE and HTTP servers. A local stdio process normally receives credentials through its environment or local configuration.

How do I remove a server?

claude mcp remove my-server

Which transport should I choose for a server on another machine?

Use SSE or HTTP, depending on the endpoint exposed by that service. Stdio is intended for a local process that Claude Code can launch directly.

Keep reading