ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Start Multiple MCP Servers at Once

Configure and run several MCP servers together in VS Code, with startup controls, security guidance, troubleshooting, and a hosted alternative.

By the ScreenshotNeo team1 October 20266 min read

Direct answer: define each MCP server as a separate, uniquely named entry in your client’s MCP configuration, then start and manage the configured servers from that client. In VS Code, you can put multiple local and remote servers in one configuration file and inspect them with the MCP server controls.

The exact filename, schema, credential fields, and startup behavior vary by host. The steps below are verified for VS Code; check your client’s current documentation before copying the format to Claude Desktop, Cursor, Windsurf, or another MCP host. See the VS Code MCP server documentation for the current reference.

1. Choose where the servers should be configured

VS Code supports three useful scopes:

Scope File or action Use it when
Workspace .vscode/mcp.json with a top-level servers object Only this project should see the servers.
Portable workspace .mcp.json at the workspace root with mcpServers You want a portable configuration that an Agent Host can read directly.
User profile User MCP configuration The same servers should be available across workspaces.
Command Palette MCP: Add Server You prefer an interactive setup.

Do not mix the two JSON shapes. .vscode/mcp.json uses servers; portable .mcp.json uses mcpServers.

2. Add several servers to .vscode/mcp.json

Create .vscode/mcp.json and give every server a unique key. This example puts a remote GitHub MCP server and a local Playwright MCP server in the same configuration:

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

The remote entry tells VS Code where to connect. The local entry tells VS Code which process to launch and which arguments to pass. Add more siblings under servers; do not nest one server inside another.

3. Use the portable .mcp.json format

If your workflow uses the portable workspace format, the equivalent structure is:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

VS Code documents that the Agent Host reads .mcp.json (or the user ~/.copilot/mcp-config.json) directly, while VS Code forwards eligible servers from .vscode/mcp.json. This is why a configuration can work in one session and appear missing in another.

4. Start, inspect, and stop the configured servers

  1. Open the workspace containing your MCP configuration.
  2. Review each publisher, URL, command, argument, and credential reference.
  3. Open the Command Palette and run MCP: List Servers.
  4. Select a server to start it, restart it, stop it, or view its details.
  5. Use Show Output for process logs and connection errors.

Starting multiple servers does not mean they share one process. Each local definition has its own lifecycle, environment, permissions, and logs; each remote definition has its own connection.

5. Control automatic startup

VS Code documents three automatic-start modes:

  • never: do not automatically start configured servers.
  • onlyNew: automatically start newly added servers.
  • newAndOutdated: start newly added and outdated servers; this is documented as the default.

Disabled or errored servers are excluded from that automatic pass. Agent Host sessions can manage processes from their own configuration, so changing VS Code’s autostart setting does not necessarily prevent an Agent Host from starting a server it discovers independently.

6. Keep local execution and credentials safe

Local MCP servers execute commands on the machine where they are configured. Microsoft warns that “Local MCP servers can run arbitrary code on your machine.” Treat every command, package, and publisher as executable software.

  • Inspect the source and package name before approving a local server.
  • Do not hardcode API keys, tokens, or passwords in committed JSON.
  • Use the host’s supported secret or environment-variable mechanism.
  • Keep workspace trust enabled and review trust prompts carefully.
  • Use remote-workspace configuration when the server is intended to run on the remote machine.

7. A repeatable setup checklist

  1. Decide whether the scope is one workspace, portable, or user-wide.
  2. Choose the schema required by that scope.
  3. Give every server a unique, descriptive name.
  4. Confirm whether each server is local or remote.
  5. Verify commands, package versions, URLs, and authentication sources.
  6. Start one server and inspect its output.
  7. Start the remaining servers and confirm each appears in MCP: List Servers.
  8. Open a chat or agent session and verify that the expected tools are available.

8. Troubleshooting multiple MCP servers

Only one server appears

Cause: invalid JSON, duplicate names, or the wrong schema for the file. Fix: validate the JSON, ensure every key is unique, and use servers only in .vscode/mcp.json or mcpServers only in portable .mcp.json.

A local server fails immediately

Cause: the command is missing, the package cannot be downloaded, Node.js is unavailable, or an argument is incorrect. Fix: run the command manually in a terminal, check the VS Code output log, confirm the working environment, and pin a known package version when reproducibility matters.

A remote server will not connect

Cause: an incorrect URL, expired authentication, network policy, or a server that is temporarily unavailable. Fix: verify the endpoint in the provider’s documentation, refresh credentials through the supported flow, and inspect the MCP output channel for the HTTP error.

The server starts in the wrong place

Cause: local and remote workspace execution differ. Fix: place the configuration in the environment where the process should run and confirm the active remote window before starting it.

Tools are missing from an agent session

Cause: the server process is running but the agent host did not load that configuration, or the server is disabled or errored. Fix: check the host-specific configuration path, run MCP: List Servers, restart the server, and start a new agent session.

Startup becomes slow or unreliable

Cause: many local packages are downloading or initializing at once. Fix: pin versions, avoid launching unused servers automatically, and start only the servers required for the current task.

9. Performance, reliability, and cost considerations

  • Startup time: local servers may spend time installing packages, launching browsers, or loading dependencies. Remote servers avoid local process startup but depend on network latency.
  • Resource use: each local server can consume its own CPU, memory, file descriptors, and child processes. Browser-backed servers are usually heavier than simple protocol servers.
  • Reliability: isolate failures by naming and monitoring servers independently. A failed server should be restarted without assuming the others failed.
  • Credentials: keep secrets outside source-controlled configuration and grant each server only the access it needs.
  • Cost: the MCP configuration itself has no universal fee. Costs depend on the remote provider, model usage, network, and any local infrastructure you run.

10. When a hosted screenshot MCP server is simpler

If one of your servers exists only to capture webpages, you can avoid maintaining a browser process. ScreenshotNeo provides a screenshot API and MCP server for AI agents, including Claude, Cursor, and other MCP clients. It removes cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Every response identifies the page verdict and billing status.

Or skip the browser setup

Make one request to the API instead of installing and operating a browser MCP process. See the ScreenshotNeo API documentation for the complete option list.

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,
)
r.raise_for_status()
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}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', data);

ScreenshotNeo also supports full-page and element capture, dark mode, device presets, custom CSS and JavaScript, waits, request blocking, headers and cookies, PDFs, caching, signed links, asynchronous jobs, bulk capture, and a usage API. There are 1,000 free shots each month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

11. FAQ

Can I start local and remote MCP servers together?

Yes. VS Code’s documented configuration can contain both types as separate named entries.

Do all MCP clients use the same file?

No. File names, schemas, authentication, and lifecycle behavior are host-specific.

Does automatic startup guarantee that every server runs?

No. Disabled or errored servers are skipped, and Agent Host sessions can apply their own configuration and lifecycle rules.

Should I put API keys directly in JSON?

No. Use the client’s supported secret or environment-variable mechanism and keep credentials out of source control.

How do I diagnose a server that starts but provides no tools?

Inspect the server output, verify that the active host loaded the intended configuration, and restart the server or agent session after correcting the configuration.

Keep reading