MCP setup guide: connect any MCP server to NearWork
Updated 2026-11-12
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:
{
"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:stdioorhttp. When omitted NearWork infers it from whethercommandorurlis 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:
- On startup only the plugin manifest is loaded (which servers exist, what tools they expose);
- When the model decides the task needs one, it enables that server on demand and calls the specific tool;
- 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.
- Just installed and still finding your feet? Go back to the quick start.
- Want to know how tool calls are billed? See the pricing page.
