Add a Remote MCP Server to LM Studio (mcp.json)

LM Studio takes a remote MCP server as one entry with a url in its mcp.json file [1]:

{
  "mcpServers": {
    "my-server": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}

The file is ~/.lmstudio/mcp.json on macOS and Linux, and %USERPROFILE%/.lmstudio/mcp.json on Windows [2]. You do not have to find it by hand: in the app, open the Program tab in the right-hand sidebar and click Install > Edit mcp.json, which opens it in LM Studio's own editor [1].

Everything below is checked against LM Studio's MCP documentation and its MCP release post on 26 October 2026 [1][2].

TL;DR:

You need LM Studio 0.3.17 or later. Remote servers are supported from 0.3.17 (b10) [1].
The format is Cursor's. LM Studio follows Cursor's mcp.json notation [1], so an entry written for Cursor works here.
A key goes in headers. The documented way to authenticate is an Authorization header in the entry [1].
Every tool call asks first. You can review and edit the arguments, then allow the tool once or always [2].

Add the server

By editing mcp.json

Open the file from Program > Install > Edit mcp.json [1] and add your server under mcpServers, as in the example at the top. The URL is the MCP endpoint itself, usually ending in /mcp, not the product's homepage or its docs page.

When you copy an entry from a server's README into a file that already has servers, LM Studio's docs say to copy only what sits inside "mcpServers": { and its closing } [1]. Pasting a whole snippet, mcpServers and all, inside the existing one nests a second mcpServers object, which is what that instruction is there to prevent.

With the Add to LM Studio button

Some servers publish an Add to LM Studio button. It is a link to lmstudio.ai/install-mcp carrying the server's name and its JSON entry, and following it opens LM Studio to add that entry for you [2]. If you build a server, LM Studio's release post has a generator for that link and the button image [2].

Add a key or token

A server that takes an API key gets a headers object next to its url. This is LM Studio's own example, for the Hugging Face MCP server [1]:

{
  "mcpServers": {
    "hf-mcp-server": {
      "url": "https://huggingface.co/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_HF_TOKEN>"
      }
    }
  }
}

Replace the placeholder with the real token [1]. The token then sits in mcp.json in plain text, so keep that file out of anything you share or commit.

LM Studio's MCP documentation describes this header and nothing else for authentication [1][2]. A server that only accepts an OAuth sign-in, and answers a plain request with 401, is one to try in a client whose documentation covers that sign-in, such as Claude Code or Cursor. MCP OAuth explains what that sign-in involves.

Approve tool calls

When the model calls one of the server's tools, LM Studio shows a confirmation dialog first. You can read the arguments the model chose, edit them, and then allow the tool once or always [2]. The tools you have allowed are listed under App Settings > Tools & Integrations, where you can manage them [2].

The model has to support tool calling for any of this to happen. A model that cannot call tools will see the server's tools and never use them.

When it will not connect

What you see	Usual cause	Fix
No MCP option, or the remote entry is ignored	LM Studio older than 0.3.17 (b10) [1]	Update LM Studio
The server does not appear after you save	A second `mcpServers` object pasted inside the first, or a JSON syntax error	Paste only the entries, inside the existing `mcpServers` [1]
No tools, or an error from the server	The URL is the homepage or docs page	Use the endpoint, usually ending in `/mcp`
`401 Unauthorized`	No `headers`, a wrong token, or a server that only takes an OAuth sign-in	Add or fix the `Authorization` header; see the section above for OAuth-only servers
The model never calls a tool	The model does not support tool calling	Load a model that does
Answers get cut off or the context fills up	The server returns more text than a local model's context holds	LM Studio warns some servers use "excessive amounts of tokens" [1]; disable tools you do not need or use a model with a longer context

For what a server's own error codes mean, see MCP server errors and MCP server connection failed. A server with many tools also costs context on every request; how many tools an MCP server should have has the numbers from 694 real servers.

LM Studio connects from your own machine, so a server on localhost or your VPN works for you and for nobody else. Our MCP connection test calls your server from our network, runs the handshake and tools/list, and reports what a stranger on the internet gets back, with a dated URL you can share. If it passes there and fails in LM Studio, the problem is in your mcp.json, not the server.

The same setup in other clients is in Cursor, VS Code, Cline, Windsurf, Claude Code, Codex, Gemini CLI, GitHub Copilot CLI, Claude Desktop and ChatGPT, and remote MCP server vs stdio covers whether your server should have a public address at all.