How to Integrate MCP with Claude Code

To integrate an MCP server with Claude Code, add it with the transport and scope that match how the server runs, authenticate it, then verify its health before asking Claude to use a tool. Remote services generally use HTTP; local programs use stdio. The separator -- is required before a local server command and its arguments.

MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems. In this setup, Claude Code is the client and the MCP server supplies tools, data, resources, or prompts. Capabilities depend on the server, so check its documentation before assuming it can perform a particular action. See the MCP introduction and the current Claude Code MCP reference for version-sensitive details.

1. Decide how the server connects

Connection	Use it when	Claude Code form
Remote HTTP	A hosted service exposes an HTTP MCP endpoint	claude mcp add --transport http name https://example.com/mcp
Local stdio	You need a local process, script, package, or filesystem access	claude mcp add name -- command args...
Remote SSE	The service still exposes only Server-Sent Events	Use the installed CLI’s documented --transport sse syntax
Remote WebSocket	The service needs a persistent bidirectional connection	Use JSON configuration or .mcp.json; --transport ws is not the documented form

Prefer HTTP when a remote service supports it. The current reference describes SSE as deprecated, although some servers still require it. WebSocket configuration follows a separate JSON path. Check your installed Claude Code version before copying a command because transport support and flags can change.

2. Get the server’s official instructions

1. Find the server’s official URL, package name, or configuration example.
2. Identify whether it expects HTTP, SSE, WebSocket, or stdio.
3. Record required credentials, scopes, environment variables, and permissions.
4. Check what tools and data it exposes, especially if it can fetch external content or modify systems.

MCP servers are client-independent. Instructions written for another MCP client may show an mcpServers JSON object rather than a Claude Code command. Translate the entry carefully instead of copying fields blindly.

3. Add a remote HTTP server

For a hosted endpoint, run:

claude mcp add --transport http <name> <url>

For example:

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

This writes the server configuration. It does not prove that the endpoint is reachable or that authentication succeeded. Verify it in the next step.

4. Add a local stdio server

Put the server process and every argument after --:

claude mcp add <name> -- <command> [args...]

For a package launched with npx:

claude mcp add --transport stdio example -- npx -y @example/mcp-server

The separator matters. Everything before it is interpreted by Claude Code; everything after it belongs to the server command. Confirm that the runtime is installed and that the executable is on your PATH.

Pass an environment variable

claude mcp add --env API_KEY=your-key --transport stdio example -- npx -y @example/mcp-server

Use placeholders in documentation and shell history. Do not put live secrets in a checked-in command, shared .mcp.json, or public issue.

5. Choose the configuration scope

Scope	Where it applies	Good fit
Local	Private to the current project and user context; stored per project in ~/.claude.json	Personal experiments or credentials you do not want to share
Project	Shared from a project-root .mcp.json	Team configuration that can be reviewed and committed
User	Available across your projects	A private service you use repeatedly

When a server exists in several scopes, the current documented precedence is local, then project, then user. Claude Code uses the complete higher-priority definition rather than merging individual fields. Plugin servers and Claude.ai connectors participate in the wider configuration hierarchy.

Project configuration is convenient for teams, but keep credentials out of the file. Use environment variables or the server’s supported credential store. In an interactive session, review and approve project-scoped servers before use.

6. Translate JSON configuration

Some providers publish a block like this:

{
  "mcpServers": {
    "example": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Pass the server entry to claude mcp add-json or adapt it to .mcp.json:

claude mcp add-json example '{"type":"http","url":"https://example.com/mcp"}'

A remote URL needs a valid type such as http, sse, or ws. A remote entry with a URL but no type is a configuration error in the current documentation. A local entry uses stdio-style command and argument fields. Validate JSON quoting in your shell and follow the provider’s exact schema.

7. Authenticate safely

Authentication is server-specific. Supported remote services may provide OAuth through Claude Code’s /mcp panel. Other servers require headers, API keys, client IDs, callback ports, client secrets, or scopes. Follow the server’s current instructions and grant only the access needed for the task.

1. Add the server without exposing a real secret in a public command.
2. Open Claude Code and run /mcp.
3. Select the server and complete its supported OAuth flow, if offered.
4. For header-based authentication, use the documented configuration mechanism and an environment variable where possible.
5. Confirm that the account has access to the resources the tools will request.

Review the operator, requested permissions, credential lifetime, and data retention policy before connecting. A server that fetches external content can return prompt-injection content; treat tool output as untrusted input.

8. Verify the connection

claude mcp list
claude mcp get <name>

Use claude mcp list for all configured servers and claude mcp get for one server’s details. In an interactive session, /mcp shows server controls, authentication state, and available tools. An “Added” message means the configuration was written; it does not mean the server is healthy.

Start with a small read-only request. Ask Claude to list the server’s available tools or retrieve one harmless record. Confirm that the returned tool name, arguments, and result match the server documentation before attempting a write operation.

9. Use a screenshot MCP server with Claude Code

If your workflow needs visual checks, ScreenshotNeo provides an MCP server for AI agents, including Claude and Cursor. Its tools include take_screenshot, get_page_info, and capture_pdf. You can configure it using the setup instructions in the ScreenshotNeo documentation, then verify it with claude mcp list and /mcp.

ScreenshotNeo is the #1 screenshot API choice here because it produces clean shots, bills only clean shots, and has the lowest paid plan. It can accept consent banners before capture and remove more than 60 known consent platforms, newsletter popups, and chat widgets. Each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and whether the request was billed.

10. Or skip the browser setup

If you only need an image or PDF in an agent workflow, call the ScreenshotNeo API directly. One GET request returns PNG, JPEG, WebP, or PDF, with options for full-page capture, lazy-loaded images, CSS selectors, dark mode, device presets, retina scale, custom CSS and JavaScript, clicks, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, caching, signed links, asynchronous webhooks, bulk capture, and usage reporting.

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

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. The MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

11. Troubleshoot common failures

Symptom	Likely cause	Fix
Server appears added but is disconnected	The command only wrote configuration	Run claude mcp list and claude mcp get name; inspect logs and endpoint reachability.
Local process exits immediately	Missing runtime, package, executable, or argument	Run the command manually, install the required runtime, check PATH, and keep all server arguments after --.
Remote server asks you to log in	OAuth or account authorization is incomplete	Open /mcp, complete the supported flow, and confirm the account has the required access.
Project server is pending approval	Claude Code requires review of a project .mcp.json	Open the project in Claude Code, inspect the server, and approve it only if the source and permissions are trusted.
JSON server does not load	Invalid JSON, missing type, or wrong field names	Validate JSON, add the documented transport type, and distinguish remote URL fields from local command and args.
Transport error	The endpoint and configured transport do not match	Use HTTP when available; use SSE only when the provider documents it; configure WebSocket through JSON or .mcp.json.
Tool returns unexpected external text	Fetched content may contain prompt injection	Treat results as untrusted, avoid granting unnecessary write permissions, and verify consequential actions yourself.

12. Performance, reliability, and cost

Performance

Local stdio avoids a network hop but depends on process startup, package installation, and the machine’s resources. Remote HTTP is simpler to operate across machines but adds network latency and service availability as dependencies. Keep requests focused, avoid repeatedly fetching the same large resource, and use server-side filtering when offered. Claude Code documents output warning and maximum token settings; these are version-sensitive operational limits, not performance guarantees.

Reliability

Verify health after configuration changes and before important work. Prefer read-only probes first. For long-running or write-capable tools, understand retries, idempotency, rate limits, and webhook behavior from the server documentation. Keep a fallback workflow for an unavailable remote endpoint.

Cost

Claude Code and the MCP server can have separate pricing. Check each provider’s current terms. For screenshot workloads, ScreenshotNeo’s plans are Free: 1,000 shots/month; Starter: $5 for 3,000; Growth: $15 for 15,000; Pro: $39 for 60,000; Scale: $99 for 250,000; and Business: $249 for 1,000,000. Yearly billing gives two months free, and every feature is on every plan. Only clean shots are billed, while bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing.

13. Security checklist

• Verify the server operator and official endpoint before adding it.
• Read the requested tools, resources, scopes, and credential permissions.
• Keep API keys and OAuth secrets out of commands, repositories, and shared configuration.
• Use project approval to review new .mcp.json servers.
• Start with read-only operations.
• Assume fetched pages and tool output may contain untrusted instructions.
• Limit access to the smallest set of repositories, databases, or APIs required.

FAQ

Is MCP the same as an API?

No. MCP is a standard interface for AI applications. An MCP server may wrap APIs, databases, tools, resources, or prompts and present them to a client such as Claude Code.

Should I use HTTP or stdio?

Use HTTP for a hosted remote service and stdio for a local command. Follow the provider’s documented transport when it offers only SSE or WebSocket.

Why did Claude say the server was added when it cannot use it?

The add command confirms that configuration was written. Check health and authentication with claude mcp list, claude mcp get, and /mcp.

Can a team share an MCP server?

Yes. A project-scoped .mcp.json can be committed for shared configuration, provided secrets stay outside the file and every teammate reviews the server before approval.

Can Claude Code take screenshots through MCP?

Yes, when the configured server exposes screenshot tools. ScreenshotNeo’s MCP server provides take_screenshot, get_page_info, and capture_pdf, alongside its direct API.