ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Set Up Your Own MCP Server in Claude Code

Connect Claude Code to a local or remote MCP server with working commands, scopes, authentication, approvals, troubleshooting, and verification steps.

By the ScreenshotNeo team1 October 20267 min read

Direct answer: Decide whether Claude Code should launch your MCP server locally over stdio or connect to a hosted server over HTTP. Build or obtain the server, register it with claude mcp add, choose a local, project, or user scope, approve it when prompted, then verify it with claude mcp list, claude mcp get, and /mcp.

MCP (Model Context Protocol) is an open standard that connects AI applications to external tools, data sources, and workflows. In Claude Code, an MCP server can expose issue trackers, databases, dashboards, design tools, APIs, or messaging systems as tools Claude can call.

1. Choose local stdio or a remote server

Decision Use this option What happens
Execution location Local stdio Claude Code launches a process on your machine and communicates through standard input and output.
Execution location Remote HTTP Claude Code connects to a hosted MCP endpoint.
Older remote service SSE Use when the service is SSE-only; HTTP is preferred where available.
Persistent bidirectional connection WebSocket Use when the server specifically provides a WebSocket transport.

For a server that needs local files, local credentials, or a development debugger, use stdio. For a shared service, central authentication, or a server running in a cloud environment, use remote HTTP.

2. Build or obtain the MCP server

You can implement a server with an MCP SDK or start from the official Claude Code scaffolding workflow. Claude Code provides an mcp-server-dev plugin:

/plugin install mcp-server-dev@claude-plugins-official
/mcp-server-dev:build-mcp-server

The builder asks about your use case and scaffolds either a remote HTTP server or a local stdio server.

A minimal local server shape

Your process must stay alive, read MCP messages from standard input, and write protocol messages to standard output. Keep diagnostic logs on standard error so they do not corrupt the protocol stream. The exact SDK calls differ by language, but the lifecycle is:

  1. Start the process.
  2. Initialize the MCP connection.
  3. Advertise one or more tools, resources, or prompts.
  4. Handle calls and return structured results.
  5. Exit cleanly when Claude Code closes the connection.

3. Register a local stdio server

Use claude mcp add [options] <name> -- <command> [args...]. Everything after -- is passed to your server; Claude Code does not parse those arguments.

claude mcp add --transport stdio myserver -- python server.py --port 8080

For a Node.js server:

claude mcp add --transport stdio myserver -- node server.js

For an executable:

claude mcp add --transport stdio myserver -- ./my-mcp-server

Environment variables and secrets

Pass credentials through environment variables supported by your server. Keep tokens out of committed project files and shell history where possible. If your server needs a working directory, configure it in the server command or wrapper script so Claude Code starts it consistently.

4. Register a remote HTTP server

Use the HTTP transport and provide the endpoint URL:

claude mcp add --transport http notion https://mcp.notion.com/mcp

If the endpoint requires a bearer token, add an authorization header:

claude mcp add --transport http notion https://mcp.notion.com/mcp \
  --header "Authorization: Bearer your-token"

Use --transport sse only for an SSE endpoint and --transport ws for a WebSocket endpoint. A remote URL must have an explicit transport when represented in JSON; otherwise Claude Code can interpret it as stdio.

5. Choose the configuration scope

Scope Best for Sharing behavior
Local (default) Machine-specific development setup Available only in the current local configuration.
Project A team integration used by one repository Can be represented in a committed .mcp.json; review it before committing.
User A personal server used across projects Available to that user across projects. 
claude mcp add --scope project --transport stdio myserver -- python server.py
claude mcp add --scope user --transport http shared https://example.invalid/mcp

Use project scope when teammates need the same integration. Use local scope for experiments and machine-specific paths. Use user scope for a personal service that should follow you between repositories.

6. Convert another client’s configuration

Map the source configuration to Claude Code like this:

  • A URL becomes a remote HTTP, SSE, or WebSocket server.
  • A launch command becomes a local stdio server.
  • An mcpServers object can be passed to claude mcp add-json after extracting one server object.

For JSON, include a transport type for every URL entry:

{
  "name": "my-remote-server",
  "type": "http",
  "url": "https://service.example/mcp"
}

Use type values such as http, sse, or ws according to the service documentation.

7. Approve and verify the connection

Project servers can remain pending until the workspace is trusted and you approve the server interactively. After adding a server, run:

claude mcp list
claude mcp get myserver

Inside Claude Code, use:

/mcp

Check whether the server is connected, requires authentication, or has failed. WebSocket servers do not appear in claude mcp list; inspect them with claude mcp get <name> or /mcp.

8. Test the tools exposed by your server

  1. Confirm the server is listed as connected.
  2. Ask Claude Code to describe the available MCP tools.
  3. Run a read-only operation first, such as listing records or fetching metadata.
  4. Verify the returned data and permissions before enabling write operations.
  5. Test the failure path by using an invalid input in a safe development environment.

A useful server returns clear input validation errors, bounded results, and structured output. Document required parameters, authentication, rate limits, and side effects in each tool description.

9. Secure your MCP integration

  • Connect only to servers you trust.
  • Review source code or deployment ownership before granting access.
  • Keep credentials in environment variables or request headers rather than committed configuration.
  • Give the server the smallest practical set of permissions.
  • Be cautious with servers that fetch external content: retrieved content can contain prompt-injection instructions.
  • Use project configuration only after checking that it contains no secrets or machine-specific paths.

10. Troubleshooting

Symptom Cause Fix
Claude tries to launch a remote URL as a process The JSON entry has a URL but no transport type. Add type: "http", type: "sse", or type: "ws".
--port or another server flag is rejected The argument was placed before the separator. Put every server argument after --.
Project server says “Pending approval” The workspace is not trusted or approval has not been granted. Trust the workspace and approve the server interactively.
Server shows “failed” Startup command, dependency, credentials, URL, or transport is incorrect. Run claude mcp get <name>, check the command independently, then correct the configuration.
Authentication required The endpoint needs a token or other credentials. Provide the documented header or environment variable and retry.
WebSocket server is missing from the list WebSocket servers are not shown by claude mcp list. Use claude mcp get <name> or /mcp.
Local server connects and immediately exits The process terminated, wrote protocol data incorrectly, or logged to stdout. Keep the process alive, send logs to stderr, and validate the SDK transport implementation.
Tools are visible but calls fail Input schema, permissions, or downstream API access is wrong. Try a read-only call, validate each argument, and inspect the server’s error output.

11. Reliability, performance, and cost

Local stdio

Startup time includes launching the process and loading dependencies. Keep initialization lightweight, reuse connections to downstream services, and avoid doing expensive discovery work before the first request. A supervisor or wrapper can restart a crashed process during development.

Remote HTTP

Account for network latency, endpoint availability, authentication expiry, and reconnect behavior. Set reasonable server-side timeouts, return bounded results, and make retries safe for operations that can mutate data. HTTP is generally the practical choice for a shared hosted service; use SSE or WebSocket only when the service requires it.

Cost

Claude Code itself does not make an MCP server free to operate. Your costs can include compute, hosting, database access, third-party API usage, and egress. Track expensive tool calls and add limits where a tool can return large datasets or trigger paid downstream operations.

12. Or skip the browser setup

If your MCP workflow needs screenshots, ScreenshotNeo provides a website screenshot API and MCP server. Its MCP tools include take_screenshot, get_page_info, and capture_pdf, so Claude Code or another MCP client can request captures without you maintaining a browser process.

One GET request returns PNG, JPEG, WebP, or PDF output:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
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)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo documentation for the full API and MCP setup. Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result. You get 1,000 screenshots each month for free with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account.

13. FAQ

Can I use more than one MCP server?

Yes. Add each server with a unique name, then inspect the combined configuration with claude mcp list and /mcp.

Should a team server use project scope?

Usually. Project scope makes the integration available with the repository configuration, while local scope stays machine-specific.

Is SSE still supported?

Older SSE-only services remain supported, but use HTTP when the service offers it.

How do I remove a server?

Use Claude Code’s MCP management commands for the server name, then confirm with claude mcp list. The exact removal command can vary by Claude Code version.

Why should logs go to stderr for stdio?

Stdout carries protocol messages. Diagnostic text there can make otherwise valid MCP messages unparsable.

Keep reading