Configuring MCP Servers

MCP servers are configured in plain JSON — no installer, no registry. There are two config files: a global one that applies to every project, and an optional project one committed alongside your code. This page covers both files, the full config syntax for local and remote servers, the per-server options, and the built-in Playwright server. If you are new to MCP, read the MCP Overview first.

The two config files

Scope	File	How to open it
Global	mcp_settings.json (stored in Nexgile Code’s settings directory)	Settings → MCP Servers → Edit Global MCP
Project	.nexgile/mcp.json (workspace root)	Settings → MCP Servers → Edit Project MCP

Both buttons create the file with an empty skeleton if it doesn’t exist yet, then open it in the editor. Both files share the same shape — a single mcpServers map:

{
  "mcpServers": {

  }
}

Servers from both files are merged. If the same server name appears in both, the project definition wins — useful for pinning a project-specific version or credentials. Changes are hot-reloaded: both files are watched, and edits reconnect the affected servers without a restart.

Tip

Put personal servers (your GitHub token, your Slack workspace) in the global file, and team-shared servers in .nexgile/mcp.json so they ride along with the repository. Keep secrets out of the project file — use ${env:VAR} interpolation instead (below).

Local (stdio) servers

A stdio server is a program Nexgile Code launches as a child process. You provide the command, plus optional args and env:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}"
      },
      "timeout": 60,
      "alwaysAllow": ["get_issue"],
      "disabledTools": []
    }
  }
}

Field by field:

• command (required) — the executable to run. On Windows, plain commands like npx work; Nexgile Code wraps them appropriately.
• args — array of command-line arguments.
• env — environment variables for the server process, on top of your normal environment.
• cwd — working directory for the process; defaults to the current workspace folder.
• type — optional for stdio; "stdio" is inferred when command is present.

Two variables are interpolated anywhere in the config:

• ${env:VAR} — replaced with the value of environment variable VAR. This is how you reference tokens without committing them.
• ${workspaceFolder} — replaced with the absolute path of the current workspace folder.

Remote servers (SSE and Streamable HTTP)

Remote servers are already running at a URL. Use url plus an explicit type — when url is present you must specify type as either "sse" or "streamable-http":

{
  "mcpServers": {
    "team-docs": {
      "type": "streamable-http",
      "url": "https://mcp.internal.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:TEAM_DOCS_TOKEN}"
      }
    },
    "legacy-search": {
      "type": "sse",
      "url": "https://legacy.example.com/sse",
      "headers": {}
    }
  }
}

• url (required) — must be a valid URL.
• headers — optional HTTP headers, typically for authentication.
• Remote entries must not mix in stdio fields (command/args/env), and vice versa — the config validator rejects mixed entries with a clear error message.

Per-server options

These work on every server, regardless of transport:

Option	Type	Default	Effect
disabled	boolean	false	Keeps the entry but never connects; the server’s tools disappear from the agent
timeout	number (seconds, 1–3600)	60	Maximum time to wait for any single response from this server
alwaysAllow	string array	[]	Tool names auto-approved for this server (only takes effect with the MCP auto-approve toggle — see Using MCP Tools)
disabledTools	string array	[]	Tool names hidden from the model entirely
watchPaths	string array	—	File paths to watch; changes restart the server (handy while developing your own server)

You rarely edit alwaysAllow and disabledTools by hand — the checkboxes and toggles in the MCP Servers view write them into this file for you. The per-server Network Timeout dropdown in that view (15 seconds up to 60 minutes) writes the timeout field.

Lazy start

Configured servers don’t all spawn at startup. When a server’s tool inventory is already known from a previous session and its config hasn’t changed, Nexgile Code registers it in a cached state: its tools appear in the UI and are advertised to the model, but the actual process or connection starts only on the first tool call — or when you press Retry Connection in the MCP Servers view. This keeps window reloads fast and avoids launching servers you don’t end up using. Expect the first call to a cold server to take a little longer than subsequent ones.

The built-in Playwright server

Nexgile Code ships with one built-in MCP server: playwright, which provides browser automation (navigate, click, type, screenshot, and more) backed by npx -y @playwright/mcp@latest. It’s registered automatically — no config needed — with a 240-second timeout, because the very first use may download the Playwright package and launch a browser.

Built-in servers behave slightly differently from ones you add:

• They cannot be deleted, only disabled ("disabled": true).
• You may override only these fields on them: disabled, timeout, alwaysAllow, disabledTools, and env. Identity fields (command, args, type) are always forced back to the shipped values, so a stale config can’t redirect the server to a different binary.
• Playwright is lazy-started: it never spawns at window load. The user pressing Retry Connection, or the agent making its first browser call, is what launches it.

To turn it off, add this to your global mcp_settings.json (or untoggle it in the MCP Servers view):

{
  "mcpServers": {
    "playwright": { "disabled": true }
  }
}

Connecting an issue tracker (Jira, Linear, and others)

Playwright is the only built-in server. Jira, Linear, Asana, ServiceNow and the rest are not bundled — you add them yourself as ordinary MCP servers, and once connected their tools behave like any other MCP tools.

Vendors ship these in one of two shapes, and which one you get decides the config:

Remote (a hosted URL). Most issue-tracker servers are hosted by the vendor and authenticate through your browser. Remember that when url is present you must state type explicitly:

{
  "mcpServers": {
    "linear": {
      "url": "https://<the-endpoint-from-your-vendor>",
      "type": "streamable-http",
      "timeout": 60,
      "alwaysAllow": []
    }
  }
}

Local (stdio). Some are npm packages you launch locally, authenticated with a token you supply:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "<the-package-your-vendor-documents>"],
      "env": {
        "JIRA_URL": "https://your-org.atlassian.net",
        "JIRA_API_TOKEN": "..."
      },
      "timeout": 60,
      "alwaysAllow": []
    }
  }
}

Take the exact endpoint URL, package name, and required environment variables from the vendor’s own current MCP documentation — those change independently of Nx IDE, and a stale value copied from a tutorial is the most common reason a tracker server won’t start.

Three practical rules:

• Put credential-bearing servers in the global mcp_settings.json, not the project .nexgile/mcp.json. The project file is committed; your API token should not be.
• Scope the credential. A read-mostly token is enough for the majority of useful work.
• Leave alwaysAllow empty for anything that writes. Creating or transitioning a ticket notifies real people — see Using MCP Tools.

Once connected, name the server in your request so the agent reaches for the right one:

Use the jira MCP server to fetch PROJ-412, then check whether the
behavior it describes still exists in @/src/billing/invoice.ts.

Note

the five GitHub specialist modes — Issue Investigator, Issue Writer, Issue Fixer, PR Fixer, Merge Resolver — drive the gh CLI and are GitHub-specific. They do not understand Jira or Linear, and pointing them at a PROJ-412 key will not work. For non-GitHub trackers, work in 💻 Code, 🪲 Debug, or 🪃 Orchestrator and let the agent call the tracker’s MCP tools. See Specialist Modes.

The master toggle

Settings → MCP Servers → Enable MCP Servers switches the entire MCP subsystem on or off. When off, no servers connect and no MCP tool definitions are sent to the model — worth doing if you don’t use MCP, since advertising tools costs tokens on every request.

Troubleshooting

• Server stuck on “connecting” or erroring — expand the server in Settings → MCP Servers and open its Logs tab. It captures the server’s error output (missing binary, bad token, crash on startup), which almost always names the problem. Fix the config, then press Retry Connection.
• Config rejected — validation errors are shown as notifications and name the offending field. Common causes: a url entry without an explicit type, or mixing command with url in one entry.
• Changes not picked up — both config files hot-reload on save; if a server looks stale, use Refresh MCP Servers in the MCP Servers view.
• First Playwright call times out — the first run downloads a sizeable package. The 240s default timeout usually covers it; on slow networks, raise the server’s timeout and retry.

Related

• MCP Overview — concepts, transports, security model
• Using MCP Tools — approval flow, per-tool controls, walkthroughs
• Files & Directories — every special file Nexgile Code reads
• Troubleshooting — product-wide fixes