TL;DR: Add an MCP server entry to .lingcode/mcp.json (or the equivalent UI in the Mac IDE) with the server's command, args, and env. LingCode launches it as a subprocess and exposes its tools to the agent as mcp__<id>__<name> calls. Works in the Mac IDE, the CLI, and /try (HTTP transport only in /try).
An MCP server is how you give the agent a new set of typed tools β for Linear, GitHub, your database, your internal admin API, anything. Configure once; the tools show up in every conversation, namespaced and approved per-call.
The agent's built-in tools are good at what they do β read files, run shell, search code β but they all share the same shape: things you'd do in a local terminal. Plenty of real engineering work isn't local. Looking up a ticket in Linear, posting a status update to Slack, querying production for a user's row, kicking off a CI run β these are remote actions the agent can't do without a way to call out.
The naΓ―ve solution is to give the agent shell access to curl and hope it gets the API call right. This works occasionally and fails badly the rest of the time β the agent has to remember endpoints, auth headers, response shapes, error codes, all in prompt context. A wrong header is a 401; a wrong endpoint is a 404; either way, the agent is debugging with HTTP errors instead of structured feedback.
MCP β the Model Context Protocol β is the structured alternative. An MCP server is a small process that exposes typed tools (create_ticket, get_user_by_email, run_query) with explicit JSON schemas for arguments and return values. The agent sees the tool by name, calls it by name, and gets back structured data. Auth happens once, at server start; the agent doesn't see the credential.
This tutorial covers connecting an existing MCP server. (Writing your own is a separate deeper topic.) You'll learn the two transport flavors LingCode supports, where to put the config, what the namespacing looks like, and the per-tool approval flow.
An MCP server entry is a few fields:
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "mcp-server-linear"],
"env": {
"LINEAR_API_KEY": "lin_api_..."
}
}
}
}That's the minimum: a unique name (linear), a command + args to launch the server, and the env vars it needs. LingCode spawns the process when the agent starts a turn, talks to it over stdin/stdout, and shuts it down between turns to keep things tidy.
MCP supports two transports:
url instead of a command; pass auth in headers. Use this when the server lives on a teammate's machine, a shared internal service, or a managed third-party provider.Both speak the same protocol β the only difference is how the connection is made. The agent doesn't know or care which transport its server is using.
Three places LingCode looks for MCP server configs:
~/.claude/mcp.json β applies everywhere. Right for personal-account services (your Linear, your GitHub)..claude/mcp.json in the project root or an ancestor β applies only when working in that project. Right for project-specific services (this product's admin API).mcp/ directory. Right for shareable, namespaced tools (a team-shared "Linear via mcp-server-linear" plugin you all install).All three are merged at load time. Project-local overrides user-wide on name collision.
mcp__<server>__<tool>When the server registers, LingCode discovers its tools and surfaces them to the agent with names like mcp__linear__create_issue, mcp__linear__list_projects, etc. The prefix matters: it keeps two MCP servers that both expose create_issue from colliding, and it lets you immediately see in the chat panel that a given tool call came from MCP rather than the built-in toolset.
The first time the agent calls each MCP tool in a session, you'll get a permission prompt with the tool's name, the arguments, and the server identity. Approve, deny, or "approve for this session." The approval is per-tool, not per-server β a deliberate choice, because some MCP servers expose powerful tools alongside benign ones.
Server won't start. Run lingcode doctor (or /doctor in the REPL). It tries to launch each configured MCP server and reports stderr from any that fail. The common causes: a missing npx/node on PATH, a required env var not set, a server package that hasn't been published yet (typo in the npm name). The fix is usually obvious once you've seen the actual error.
Server starts, tools don't show. The server is up but isn't registering anything. This usually means a schema problem on the server side β the tool definitions exist in code but don't pass validation, so the agent never sees them. Check the server's own logs; the schemas usually fail noisily. If the server is third-party and recent, file an issue upstream.
Don't put LINEAR_API_KEY as a literal string in mcp.json if the file lives in version control. Either commit a template ($LINEAR_API_KEY) and let the env supply it, or put the real config in ~/.claude/mcp.json (which is per-user and not committed). MCP servers are powerful β leaking the credential is the same risk class as leaking any other API key.