MCP Servers for Coding Agents, Explained

Published September 26, 2026 · by the AQ team

An MCP server is a small program that gives an AI coding agent extra tools (query a database, read Linear issues, search docs, control a browser) over the Model Context Protocol, an open standard Anthropic introduced on November 25, 2024 that has since been adopted across the industry, including by OpenAI in March 2025. Claude Code, Codex, Cursor, and OpenCode all speak it, which is why one Linear or Postgres server works from any of them. Each agent configures servers in its own file with its own syntax: this guide covers the exact file and syntax for each of the four as of September 2026, how a team shares one configuration, and the security rules that matter now that malicious MCP servers have been found in the wild.

What is an MCP server?

The Model Context Protocol (MCP) standardizes how an AI application talks to external tools and data: a client (your coding agent) connects to servers, each server advertises a list of tools with typed inputs, and the model calls those tools mid-task. The protocol is JSON-RPC 2.0 under the hood, with two transports that matter in practice: stdio, where the agent launches the server as a local child process and talks over stdin/stdout, and streamable HTTP, where the agent connects to a remote URL (often with OAuth, which the March 2025 spec revision added). Servers can also expose resources and prompts, but for coding agents, tools do the work.

Why it matters for coding: an agent without MCP can only see the repository and run shell commands. With the right two or three servers it can read the ticket it is implementing, query the staging database schema instead of guessing, or pull the stack trace behind the bug from the error tracker.

How each coding agent configures MCP servers

Same protocol, four different config files. All details below are from each vendor's documentation as of September 2026.

Claude Code

Claude Code manages servers with the claude mcp add command and three scopes. Local scope (the default) stores the server in your ~/.claude.json for the current project only. User scope (--scope user) stores it in the same file for all your projects. Project scope (--scope project) writes a .mcp.json file at the repository root, which you commit so the whole team gets it:

# Remote server over streamable HTTP
claude mcp add --transport http linear https://mcp.linear.app/mcp

# Local stdio server, with an env var, shared with the team
claude mcp add --scope project --env AIRTABLE_API_KEY=YOUR_KEY   --transport stdio airtable -- npx -y airtable-mcp-server

The .mcp.json file supports environment variable placeholders (a dollar sign with the variable name in braces, for example ${API_KEY}) in commands, args, env, URLs, and headers, so it can be committed without committing secrets. The first time Claude Code sees a project-scoped server it asks you to approve it, so a cloned repository cannot silently launch processes on your machine. OAuth-protected remote servers authenticate via the /mcp command in a session or claude mcp login from the shell. Tool outputs are capped at 25,000 tokens by default (warning at 10,000; raise the cap with MAX_MCP_OUTPUT_TOKENS), and organizations can pin or block servers fleet-wide with the managedMcpServers setting.

Codex

Codex keeps MCP servers in ~/.codex/config.toml as one TOML table per server, written by hand or via codex mcp add. A stdio server takes command, args, and env; a remote server takes a url, connecting over streamable HTTP:

# ~/.codex/config.toml
[mcp_servers.linear]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.linear.app/sse"]

[mcp_servers.internal-api]
url = "https://mcp.internal.example.com/mcp"
bearer_token_env_var = "INTERNAL_MCP_TOKEN"

The bearer_token_env_var field is the credential pattern to copy: Codex reads the token from the process environment and sends it as an Authorization header, so the secret never sits in the file. Per-server startup_timeout_sec and tool_timeout_sec handle slow servers, and the config is per user, not per repository, which matters for teams (more below).

Cursor

Cursor reads .cursor/mcp.json in the project (commit it to share with the team) and ~/.cursor/mcp.json globally, with the project file winning when both define the same server. The format is the same mcpServers object Claude Code uses: stdio servers take command, args, and env; remote servers take url and headers, with browser-based OAuth on first connection. Cursor also supports one-click install links (the "Add to Cursor" buttons on server docs pages) that prefill the config. Two notes from its docs as of September 2026: servers load at startup, so config edits need a restart, and Cursor caps active tools at roughly 40 across all servers combined, past which the agent silently loses access to some.

OpenCode

OpenCode configures servers under the mcp key of its config: ~/.config/opencode/opencode.json globally, or an opencode.json at the project root for that repository. Each entry declares its type explicitly:

{
  "mcp": {
    "github": {
      "type": "remote",
      "url": "https://api.githubcopilot.com/mcp/",
      "enabled": true,
      "headers": { "Authorization": "Bearer {env:GITHUB_TOKEN}" }
    },
    "local-tools": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-server"]
    }
  }
}

The {env:NAME} placeholder substitutes environment variables at load time, local servers take an environment map, remote servers can authenticate over OAuth, and the enabled flag turns a server off without deleting it.

How a team shares one MCP configuration

The default failure mode is per-laptop drift: one engineer has the Linear server, another has a stale token, a third pointed the database server at production. Treat MCP config as code:

• Commit the project-scope file. Claude Code's .mcp.json, Cursor's .cursor/mcp.json, and OpenCode's opencode.json all live in the repository, so a checkout carries the team's servers. Reference secrets through each tool's environment placeholders; the values stay in each person's environment or secret manager, never in git. It is the same discipline as sharing agent skills across a team.
• Cover the per-user tools with a setup script. Codex config is per user as of September 2026, so put the canonical [mcp_servers] tables in a bootstrap script or dotfiles template rather than a wiki page that rots.
• Keep the approval prompts. Claude Code asks before running a project-scoped server from a fresh clone. That prompt is what stops a malicious .mcp.json in a cloned repo from executing code on sight. Do not train the team to bypass it.
• Run agents somewhere consistent. Config drift is a symptom of agents running on N different laptops. A shared, provisioned machine makes the environment one artifact to manage instead of N.

The security rules

An MCP server runs with your credentials and feeds text directly to your agent, which makes it both a supply-chain and a prompt-injection surface. This is not theoretical: in September 2025 a rogue npm package called postmark-mcp shipped a malicious update that silently blind-copied every email sent through it to an attacker's address, reaching roughly 1,500 weekly downloads before Koi Security flagged it. The rules that follow:

• Install from the vendor, not from search results. Prefer the official server for each service, pin versions, and treat an unknown npm package that wraps a popular API as guilty until proven otherwise.
• Scope every credential to the narrowest permission the job needs. A read-only database user for the schema server, a repo-scoped token instead of an org-wide one. Anything a server can read, the model can see and an injected prompt can try to exfiltrate: keeping secrets out of coding agent prompts covers this half in depth.
• Treat tool output as untrusted input. A ticket body, web page, or database row fetched by a server can carry instructions aimed at your agent (indirect prompt injection). Keep approval prompts on for anything that writes, sends, spends, or deletes.
• Control egress where you can. A stdio server is a process with your shell's network access. An isolated machine with a firewall beats hoping every dependency behaves.

Why three to six servers beat fifteen

Every connected server's tool definitions are injected into the model's context on every request, whether or not they get used. Fifteen servers means dozens of tool schemas competing for attention: more tokens burned per turn, more chances the model picks the wrong tool, and in Cursor's case the 40-tool ceiling. The teams that get the most from MCP run a short, deliberate list (the issue tracker, the database, maybe the error tracker and a docs source), chosen because the agent needs them weekly. Start from the task rather than from a listicle, and delete servers that have not been called in a month. For a worked example, adding the Linear MCP server to Claude Code walks one high-value server end to end.

Where AQ fits

AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. MCP config is exactly the kind of environment state that drifts across laptops, and AQ's answer is to make the environment shared: agents run as real CLIs in persistent tmux sessions on your team's VM, and every workspace gets its own isolated git worktree, so the project-scoped files this guide covers (.mcp.json, .cursor/mcp.json, opencode.json) arrive with every checkout and the CLIs load them exactly as they would locally. One machine's environment to manage, and teammates can open the same workspace and watch the same live session, so when an agent uses an MCP tool, the person reviewing can see it happen. Each engineer still authenticates the CLIs with their own accounts (per-user CLI logins, per-user GitHub auth), and there is no shared multi-tenant execution tier: your agents, and the MCP servers they launch, run on your VM. The Free plan is a personal sandbox AQ creates for you with nothing to install; the Team plan is $50 per user per month early access (standard $200, billed monthly), covering VMs you connect from your own cloud or a dedicated always-on AQ-managed VM, rate locked for your first 12 months.