# MCP setup guide: connect any MCP server to NearWork

> NearWork speaks both stdio and HTTP MCP transports. Complete mcp.json examples, user-level versus project-level precedence, how on-demand tool loading works, and the order to debug a server that will not connect.

MCP (Model Context Protocol) is the open protocol that lets an AI call external tools: hang Notion, GitHub, a database or a browser off NearWork and the agent can read and write them directly. NearWork ships an MCP client that supports **stdio** and **HTTP** transports, configured once and reused afterwards.

## Three ways to connect, by comfort level

| Approach | Who it suits | How |
|---|---|---|
| Plugin marketplace | Almost everyone | Sidebar → Plugins → Marketplace, search and install in one click; services needing a token prompt you for it |
| Add manually | Services the marketplace does not carry | Sidebar → Plugins → Add manually, or edit `mcp.json` directly |
| Let the AI add it | You already have the parameters | Paste the service name and arguments into the chat and ask NearWork to write the config and tell you to restart |

Marketplace entries cover browser automation (Chrome DevTools, Playwright), documentation knowledge (Context7, DeepWiki), collaboration (Notion, Linear, Slack) and data stores (MongoDB, Supabase, Pinecone); the list grows with each client release.

## Where the config lives

Configuration is two-level, and **project-level overrides user-level** for a service with the same name:

| Level | Primary path | Compatible paths still read (legacy) |
|---|---|---|
| User (global) | `<LINGXI_HOME>/mcp.json` | `~/.claude/mcp.json` |
| Project | `<project>/.lingxi/mcp.json` | `.claude/mcp.json`, `.agent/mcp.json` |

`<LINGXI_HOME>` defaults to `~/.LingXi` (on Windows `C:\Users\<you>\.LingXi`) and can be redirected with an environment variable.

> Project-level config is only loaded when the current working directory matches. If you dropped a config inside a project, switch NearWork's working directory to that project or the tools will not appear.

## Writing mcp.json

One file can hold many services; the key is the service name:

```json
{
  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "my-remote": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}
```

- `type`: `stdio` or `http`. When omitted NearWork infers it from whether `command` or `url` is present, but writing it explicitly is safer.
- `command` / `args` / `env`: how a stdio server is launched.
- `url` / `headers`: endpoint and auth headers for an HTTP server.

Restart the client (or reload plugins) for changes to take effect.

## MCP tools are not all loaded up front

NearWork does not shove every MCP tool into the context on a cold start — that burns tokens and makes the model pick badly among dozens of options. The actual mechanism:

1. On startup only the *plugin manifest* is loaded (which servers exist, what tools they expose);
2. When the model decides the task needs one, it enables that server on demand and calls the specific tool;
3. You can also name the server in your prompt: "use Context7 to check the Next.js 15 caching API".

In the CLI, `/mcp list` shows connected servers and `/mcp tools` lists one server's tools.

## Frequently asked questions

### I installed a plugin but the AI says the tool does not exist

Debug in this order: (1) did you restart the client; (2) is the service name misspelled — the key in `mcp.json` *is* the service name; (3) does the stdio server rely on `npx` while your Node build is too old (the client itself needs Node.js 22+, and stdio servers run on that same runtime); (4) is a project-level config being skipped because the working directory is wrong.

### The first call is very slow or times out

Most stdio servers pull an npm package through `npx` on first launch, so a slow first start is normal. Behind a slow network, set a mirror first (`npm config set registry https://registry.npmmirror.com`) and retry.

### A remote HTTP server will not connect

NearWork's MCP client supports static-token auth only (for example `Authorization: Bearer xxx`); OAuth flows that need a browser redirect are not supported. If a service enforces OAuth, the stdio build or a different service is the way forward.

## Security notes

An MCP server is third-party software running on your machine: a stdio server can execute arbitrary commands, an HTTP server can read and write whatever it is authorized to reach. **Only install plugins from sources you trust**, and never paste a stranger's config just to make the AI "smarter". For anything destructive, keep the default permission mode so writes need confirmation.

## Next steps

- Wondering about tool permissions and dangerous-command blocking? See [Data and privacy](/en/docs/faq/data-privacy).
- Just installed and still finding your feet? Go back to the [quick start](/en/docs/start/quick-start).
- Want to know how tool calls are billed? See the [pricing page](/en/pricing).
