Introduction to Model Context Protocol

The Model Context Protocol (MCP) is the open standard that lets a coding agent such as Claude Code, Codex or Cursor call external tools and read live data: GitHub pull requests, Sentry errors, Linear tickets, a browser, a database. In September 2026 most servers worth adding are vendor-hosted remote servers with OAuth, and each server is a new trust boundary.

This page is for developers adding their first servers and tech leads deciding which ones the team may use. The situation it solves: a teammate pasted a server’s JSON into a README, half the team runs it with write access, nobody knows which package it really came from, and the agent just edited a production ticket.

What you’ll walk away with from this MCP overview

• What changed in 2026: the stateless 2026-07-28 spec, which clients support it, and the move to remote OAuth servers.
• The config file and command for each agent, tested on Claude Code 2.1.283 and codex-cli 0.157.1.
• One remote server (Sentry) added and logged in to in all three agents.
• A four-step team workflow: evaluate, scope to read-only, add at project scope, review in a PR.
• Two copy-paste prompts: one that evaluates a candidate server and one that audits what is already connected.

How MCP works in 2026

An MCP host is your agent. It holds one client connection per server, and each server exposes tools (actions), resources (data) and prompts. The agent reads each tool’s name and description, decides when to call it, and receives a structured result that becomes context for the next step.

Servers reach the agent over one of two transports:

• stdio: the agent starts the server as a local process (npx, uvx, docker run). Use it for local files, a local database, or a server that has no hosted version.
• Streamable HTTP: the server runs at a URL and usually authenticates with OAuth. GitHub, Figma, Sentry, Linear, Atlassian, Notion, Supabase, Vercel, Stripe, Cloudflare, Datadog, PostHog, Slack and GitLab all run hosted servers. The older HTTP+SSE transport is deprecated; do not pick it for new setups.

Anthropic created MCP and donated it to the Agentic AI Foundation (AAIF) on 2025-12-09.

What changed in MCP spec 2026-07-28?

The current specification revision is 2026-07-28. It makes the protocol stateless: the initialize handshake and the Mcp-Session-Id header are gone, servers must answer server/discover, and Tasks moved to an extension. It deprecates Roots, Sampling and Logging, and it deprecates Dynamic Client Registration in favour of Client ID Metadata Documents.

Clients have not all caught up, so the protocol you get depends on the agent:

Agent	Speaks 2026-07-28?	Checked
Claude Code	Yes, negotiated by default with direct HTTP servers on all installs since v2.1.274. Opt out with MCP_PROTOCOL_NEGOTIATION=legacy	changelog, 2026-09-26
Codex	No. The mcp_2026_07_28 feature is under development and off, so connections use the older protocol	codex features list, codex-cli 0.157.1
Cursor	Not verified: cursor.com was unreachable from the writing environment on 2026-09-26	—

A server that only speaks the new revision can therefore work in Claude Code and fail in Codex. MCP 2026-07-28: what changed and how to migrate a server covers the server side.

Is the Official MCP Registry a curated list?

No. The Official MCP Registry is still in preview (API frozen at v0.1 since 2025-10-24). Counted through its API on 2026-09-26, it listed between 36,176 and 36,184 servers at their latest version (the number moves hourly). The only gate is namespace verification. Several */github, */figma and */sentry entries come from publishers unrelated to those vendors. Use the registry to confirm who publishes a server, then read the vendor’s own README before you install anything. Allowlisting servers for an organization is covered in MCP registries and gateways.

Where each agent stores MCP servers

The three agents read different files, and each one fails differently when you use another agent’s syntax.

	Claude Code	Codex	Cursor
Project scope (commit it)	.mcp.json at the repo root	.codex/config.toml, read only when the project is trusted	.cursor/mcp.json
Personal scope	claude mcp add (default local scope, per project in ~/.claude.json) or --scope user	~/.codex/config.toml (what codex mcp add writes)	~/.cursor/mcp.json
Remote server	claude mcp add --transport http NAME URL	codex mcp add NAME --url URL	"url": "…" in mcpServers
Log in	/mcp in a session, or claude mcp login NAME	codex mcp login NAME	from Cursor’s MCP settings when the server asks
Check	claude mcp list, claude mcp get NAME	codex mcp list, codex mcp get NAME --json	the server’s status in Cursor’s MCP settings

The Claude Code and Codex rows were run on Claude Code 2.1.283 and codex-cli 0.157.1 on 2026-09-26, including the trusted-project behaviour of .codex/config.toml. The Cursor file shapes come from vendor READMEs (GitHub, Context7, Sentry) and were not tested in Cursor.

Add a remote MCP server in all three agents

Sentry’s hosted server is a good first remote server: it uses OAuth, needs no API key in a file, and its URL is the example printed by claude mcp add --help itself. The Official MCP Registry lists it as io.github.getsentry/sentry-mcp (0.42.0), and the repo had 862 GitHub stars (getsentry/sentry-mcp on GitHub, read 2026-09-26).

Claude Code

Run in a terminal at the repo root:

claude mcp add --transport http --scope project sentry https://mcp.sentry.dev/mcp

The command writes this entry to .mcp.json:

{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

Start claude, run /mcp, select sentry and complete the browser login (or run claude mcp login sentry from the terminal). A server from .mcp.json shows as Pending approval in claude mcp list until you approve it; after approval, claude mcp list health-checks it and shows it as connected.

Codex

Run in a terminal:

codex mcp add sentry --url https://mcp.sentry.dev/mcp
codex mcp login sentry

codex mcp add writes the server to ~/.codex/config.toml and prints a hint to run codex mcp login. codex mcp list shows the sentry row with its Status and Auth columns. To share the server with the team instead, put the same table in the repo’s .codex/config.toml:

[mcp_servers.sentry]
url = "https://mcp.sentry.dev/mcp"

Codex reads that file only after you mark the project as trusted.

Cursor

Add to .cursor/mcp.json in the repo (or ~/.cursor/mcp.json for every project):

{
  "mcpServers": {
    "sentry": {
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

Open Cursor’s MCP settings, find sentry, and sign in when it asks for authentication. This shape comes from vendor READMEs and was not tested in Cursor.

Then give the agent a read-only task and watch which tools it calls:

Copy-paste prompt: first call to a new MCP server

Using the sentry MCP server only, find the most frequent unresolved error in the project
web-frontend over the last 24 hours. Show the issue title, event count, first and last seen,
and the top three stack frames. Map each frame to a file in this repo. Do not change any code
and do not modify the issue in Sentry. List every MCP tool you called, in order.

Replace web-frontend with your Sentry project slug.

You should see calls such as search_issues followed by an issue-detail call, then local file reads. If the agent edits code or calls a tool that changes the issue, your read-only scoping (below) has a gap.

A team workflow for adding MCP servers

One developer adding a server to their personal config is an experiment. A server in the repo is a dependency every teammate and every agent session inherits, so it goes through the same path as a new package.

1. Evaluate the server. Confirm the publisher in the Official MCP Registry and the vendor’s own README, confirm the exact package name on npm or PyPI, and list its tools. Many plausible names are wrong or abandoned; the traps box below lists the common ones. Prefer the vendor’s hosted server with OAuth over a community wrapper.

2. Scope it to read-only. Use the server’s own switch first; each server spells it differently. GitHub uses a /readonly URL, Supabase read_only=true, Postgres MCP Pro --access-mode=restricted, Grafana --disable-write. Where a server has no switch, restrict tools on the client: Codex takes enabled_tools or disabled_tools per server in config.toml, and Claude Code names each tool mcp__<server>__<tool>, so a deny rule in .claude/settings.json blocks a write tool.

3. Add it at project scope. Commit .mcp.json, .codex/config.toml or .cursor/mcp.json with no credentials in them. Remote servers use OAuth per developer; a stdio server reads its token from an environment variable (--env in Codex, -e in Claude Code); a remote server that takes a token instead of OAuth reads it through Codex’s bearer_token_env_var (--bearer-token-env-var).

4. Review it in a PR. Put the three files under CODEOWNERS so a tech lead or the platform owner approves every change. The reviewer checks the diff, not the agent’s behaviour: publisher, package name and version, transport, read-only switch, and whether the server can reach data the repo should not.

Traps: MCP package names that look right

• @modelcontextprotocol/server-github is deprecated; use GitHub’s hosted server.
• @figma/mcp does not exist; Figma’s server is remote only.
• npm postgres-mcp is an unrelated package; Postgres MCP Pro is on PyPI and runs with uvx.

A CODEOWNERS entry you can adopt as-is (replace the team handle):

# MCP servers are dependencies: platform owners approve every change
/.mcp.json            @acme/platform-owners
/.codex/config.toml   @acme/platform-owners
/.cursor/mcp.json     @acme/platform-owners

Copy-paste prompt: evaluate an MCP server before adding it

We are considering the Linear MCP server for this repo. Before anything is installed, report:
1. The publisher and URL or package name, confirmed against the Official MCP Registry
   (registry.modelcontextprotocol.io) and the vendor's own README. Flag any mismatch.
2. Transport (stdio or HTTP) and auth method (OAuth, API key, none).
3. Every tool it exposes, split into read-only and write, with one line on what each write tool changes.
4. Whether it has a server-side read-only switch, and the exact flag or URL.
5. The config entry for .mcp.json, .codex/config.toml and .cursor/mcp.json, read-only, with no secrets inline.
Do not install or run the server. Mark anything you could not confirm as UNVERIFIED.

How to verify an MCP setup without reading every tool call

You do not need to watch every call to have evidence that the setup matches what you approved. Four checks give you evidence:

• Configuration is what you approved. codex mcp get NAME --json prints the resolved transport, URL, headers and tool filters; claude mcp get NAME prints scope, type, URL and approval status. Compare them with the reviewed file; a Codex headers = {…} key, for example, is silently dropped and shows up here as http_headers: null.
• Context cost is measured. Run /context in Claude Code before and after adding a server. For scale, Cloudflare quotes about 244k tokens for native schemas of its API against about 1k for its three-tool Code Mode server. Tool search is on by default in both Claude Code and Codex, which defers most schemas, but tool results still land in context. Reducing MCP token cost covers what to do when a server is expensive.
• The config is scanned. Snyk Agent Scan (uvx snyk-agent-scan@latest, PyPI 0.6.4 on 2026-09-26) scans MCP configs and skills for prompt injection and tool poisoning. It needs a Snyk API token, and it starts the stdio servers it scans, so scan untrusted configs in a sandbox. The MCP security guide shows the full setup.
• The agent reports its calls. The prompts on this page end with “list every MCP tool you called”. A write call in a read-only task is a failed check, whatever the result looked like.

Copy-paste prompt: audit the MCP servers already connected

List every MCP server connected in this session and every tool each one exposes. For each tool,
say whether it only reads or can change files, tickets, repositories, databases or cloud resources.
Then compare with the project config files (.mcp.json, .codex/config.toml, .cursor/mcp.json)
and flag: servers not in any committed file, write tools on servers the team meant as read-only,
credentials written inline, and packages whose name does not match the vendor's README.
Output a table, then a short list of recommended removals. Change nothing.

What breaks when you add an MCP server

The Claude Code server never connects. claude mcp add sentry https://mcp.sentry.dev/mcp without --transport http still succeeds: Claude Code prints a warning that is easy to miss and writes a stdio server whose command is the URL (claude mcp list then shows Failed to connect — ENOENT). Remove it with claude mcp remove sentry and add it again with --transport http. --url is Codex’s flag; Claude Code rejects it as an unknown option.

Codex ignores your token. A headers = {…} table in config.toml is ignored. Use http_headers, env_http_headers or bearer_token_env_var, then confirm with codex mcp get NAME --json. codex mcp add --env works only for stdio servers.

A server works in Claude Code and not in Codex. Codex 0.157.1 does not speak MCP 2026-07-28. Check the server’s supported protocol versions; until Codex ships the feature, use a server version that still supports the older revision.

The project file is ignored. Claude Code reads .mcp.json at the repo root, not .claude/mcp.json, and waits for your approval of each project server. Codex ignores .codex/config.toml until the project is trusted.

OAuth hangs in the browser. The callback goes to a local port that a VPN or firewall can block. Run codex mcp login NAME --no-browser to finish by pasting the callback URL. In Claude Code, a server that needs a pre-registered redirect URI takes --callback-port and --client-id on claude mcp add.

The agent calls the wrong tool. Too many servers means too many similar tool descriptions. Remove servers you have not used in a week before you rewrite prompts. MCP connection issues covers the remaining errors.

Project MCP servers run with your credentials

A committed .mcp.json starts processes on every machine and CI runner that loads it. In CI jobs triggered by untrusted pull requests (pull_request_target, issue_comment), load no project MCP config from the contributor’s checkout while secrets are in the environment. See the agent threat model.

Where to go next with MCP

Start with the ecosystem overview if you have not yet decided whether a problem needs an MCP server, a skill or a plugin. Then:

The MCP starter stack The five servers most teams need, with the exact add commands for each agent.

Top MCP servers, ranked The 30 servers that matter for software teams, with read-only switches and fake package names.

Securing MCP servers Scanning, read-only modes and prompt injection through tool results.

Building your own MCP server Write, test and publish a server for an internal API.

For per-tool setup details, see MCP setup in Claude Code, Codex and Cursor.