Claude Skills and MCP Servers in 2026: A Practitioner's Guide

If you've spent any time around Claude Code in the last six months, you've watched two extension mechanisms ship into your toolbox: Agent Skills and MCP servers. They look superficially similar — both extend what Claude can do — but they solve different problems, and the teams that get the most leverage out of Claude Code in 2026 understand exactly when to reach for each.

This guide is for engineers who already know what Claude Code is and want the practitioner's view: the SKILL.md format with reserved-word gotchas, the MCP 2025-11-25 spec with its OAuth hardening, and four worked integration patterns we see shipping in real codebases. It is not a 101 on "what is MCP" — for that, start with our AI coding agents pillar guide.

The two things, and why they're different

A Skill is a directory on disk. Inside it is a single required file, SKILL.md, containing YAML frontmatter and Markdown instructions. It may also contain helper scripts, reference documents, and templates that the instructions point at. When you ask Claude to do something, the model decides — based on the skill's name and description — whether to load the body. That's it. There is no daemon, no port, no auth flow. The skill is text that enters the context window if and only if Claude decides it's relevant.

An MCP server is a running program. It speaks the Model Context Protocol over either standard input/output (stdio, for local processes) or Streamable HTTP (for remote services). It exposes tools, resources, and prompts to any MCP client — Claude Code, Claude Desktop, Cursor, Codex CLI, or your own application. The server is where the side effects happen: it queries your database, opens a pull request, posts to Slack, refunds a Stripe charge.

The shortest accurate framing: MCP is connectivity, Skills are procedural knowledge. Add MCP when Claude needs to reach a system it cannot reach today. Add a Skill when Claude already has the access but you keep re-explaining the workflow.

What the SKILL.md format actually looks like in 2026

The format is dead simple, and once you've shipped one you understand it. Here is a minimal example you could drop into .claude/skills/code-review/SKILL.md today.

---
name: code-review
description: Use when reviewing a pull request. Pulls the diff via the GitHub MCP server, classifies changes, checks against CONTRIBUTING.md, and posts inline review comments.
allowed-tools: Bash(git:*) Read mcp__github__get_pull_request_files mcp__github__create_pending_pull_request_review
---

# Code review workflow

## When to use
- The user asks to "review PR #N" or "look at this PR".
- The user pastes a GitHub PR URL.

## Steps
1. Resolve the repo + PR number from the URL or current git remote.
2. Pull the changed files via `mcp__github__get_pull_request_files`.
3. Read `CONTRIBUTING.md` and `references/review-checklist.md` from this skill folder.
4. Classify the change: feature, refactor, test-only, dependency bump.
5. For each file in the diff, emit one of: comment, suggestion, or pass.
6. Open a pending review via `mcp__github__create_pending_pull_request_review`, add inline comments, then submit.

## What not to do
- Do not approve PRs that touch auth flows without a second human reviewer.
- Do not file nitpicks on test-only changes.

The rules that matter:

• name is required, max 64 characters, lowercase letters, digits and hyphens only, no XML tags. Reserved words: "anthropic" and "claude". Use neither in the name field — Claude Code will refuse to load the skill.
• description is required, max 1024 characters, also no XML. This is the single most important field — Claude decides whether to load the skill body based on it. Start with "Use when…" and be specific about the trigger.
• allowed-tools is optional and still marked experimental. It is a space-delimited list that scopes the skill's tool surface (for example, Bash(git:*) Read). Use it as a defense-in-depth measure — a docs-formatting skill has no business holding the GitHub write tool.
• Body should be under ~500 lines. Push anything longer into adjacent files and reference them — the agent will load them on demand.

The format is now an open standard adopted by Claude Code, OpenAI's Codex CLI, Cursor, Gemini CLI, and GitHub Copilot. The same SKILL.md works in all of them.

Where do skills live, and how are they distributed?

In Claude Code, skills resolve from three locations in priority order: enterprise-managed settings override personal, and personal overrides project.

• Personal: ~/.claude/skills/<skill-name>/SKILL.md. Available across every project you open. Use this for individual preferences — your editor style, your shortcuts.
• Project: .claude/skills/<skill-name>/SKILL.md, committed to the repo. This is how teams standardize workflows. The repo becomes the source of truth.
• Plugin marketplace: distribute as a Claude Code plugin via /plugin marketplace add <owner>/<repo>, then /plugin install. The official Anthropic-managed marketplace at anthropics/claude-plugins-official ships 101 vetted plugins as of March 2026, plus 68 partner plugins from GitHub, Playwright, Supabase, Figma, Vercel, Linear, Sentry, Stripe, and Firebase.

How does progressive disclosure keep skills cheap?

The progressive-disclosure design is what makes it sane to install dozens of skills at once. There are three loading levels:

1. Session start: Claude loads only the name and description of every available skill. Each skill consumes roughly 30-50 tokens of context budget. Fifty skills = ~2,500 tokens of overhead, which is negligible.
2. Skill invocation: When Claude decides a skill is relevant, it loads the SKILL.md body — up to ~5,000 tokens.
3. Referenced files: Additional files in the skill folder are loaded only if the body references them and the current task needs them. This is effectively unbounded.

This is why teams routinely run 20-50 skills with no measurable performance impact. The model never sees what it doesn't need.

What's actually in the MCP 2025-11-25 spec?

MCP turned one year old in November 2025. The 2025-11-25 release is the current stable specification; a 2026-07-28 release candidate is in review with a stateless protocol core and an Extensions framework. If you're shipping today, target 2025-11-25.

The pieces that matter for practitioners:

• Two transports. stdio is the path for local servers — your client spawns the server as a child process and talks over its standard streams. Streamable HTTP is the path for remote services — HTTP POST for requests, Server-Sent Events for streaming responses. Streamable HTTP replaced the older HTTP+SSE transport from the 2024-11-05 spec, and 2025-11-25 added Mcp-Method and Mcp-Name headers so load balancers can route on operation without parsing the body.
• OAuth 2.1, hardened. Remote servers must implement OAuth 2.1 for both confidential and public clients. Authorization-server discovery now uses OAuth 2.0 Protected Resource Metadata (RFC 9728): the server either responds with a 401 carrying a WWW-Authenticate header that points at the resource metadata, or it exposes /.well-known/oauth-protected-resource at the root. The spec also adds OpenID Connect Discovery 1.0 support and Resource Indicators (RFC 8707) to prevent tokens issued for one server from being replayed against another.
• Tasks. A new abstraction for tracking long-running work — the server returns a task handle, and the client polls for progress and results. This unblocks deferred and durable agent operations.
• Icons metadata for tools, resources, resource templates, and prompts.

The MCP servers worth installing in 2026

The ecosystem now has more than 10,000 public servers. Most of them you do not want. The shortlist below is what we see senior engineering teams actually pin in production:

• GitHub (github/github-mcp-server, official) — issues, PRs, repos, code search. Available as a remote server, so no local install needed.
• Linear (official remote at linear.app/docs/mcp) — issues, projects, cycles. Hosted by Linear.
• Sentry (official) — error groups, stack traces, releases. Pairs naturally with GitHub for regression bisection.
• Slack (official remote, slackapi/slack-mcp-plugin) — search, messaging, canvas. Note: workspace admins must approve MCP integration before users can connect.
• PostgreSQL (community: crystaldba/postgres-mcp, abiswas97/postgres-mcp-server) — query, schema, EXPLAIN. Read-only by default in most builds.
• Playwright (Microsoft official) — browser automation and testing.
• Stripe, Supabase, Notion, Vercel, Atlassian, HubSpot — first-party remote servers from each vendor.
• Filesystem, Memory, Time, Sequential Thinking — Anthropic's reference servers, useful for local automation.

A rule of thumb that's saved several teams I work with: prefer first-party vendor servers when they exist. The community fork you found on GitHub in early 2025 is probably no longer maintained, because GitHub, Sentry, Stripe, and Linear all shipped their own.

How do you configure MCP servers in Claude Code?

Claude Code reads MCP server config from three scopes:

• local — written to ~/.claude.json, scoped to your local checkout, private to you.
• project — .mcp.json at the repo root, committed and shared with the team.
• user — ~/.claude.json at the user level, available across every project.

Add a server with the CLI: claude mcp add github --command npx --args "-y @modelcontextprotocol/server-github" --env GITHUB_TOKEN=..., or edit the JSON by hand. A typical .mcp.json looks like this:

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" }
    },
    "postgres": {
      "type": "stdio",
      "command": "uvx",
      "args": ["postgres-mcp", "--read-only"],
      "env": { "DATABASE_URL": "${env:DATABASE_URL}" }
    },
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/sse"
    }
  }
}

Gotcha: a misplaced comma in .mcp.json silently disables every server in the file. Lint the JSON before restarting Claude Code.

Claude Desktop uses a single file: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows. Same shape, different home.

Four real integration patterns

This is what the title promises. Each of the patterns below is something I have watched ship in 2026; the SKILL.md sketches are tight enough to drop into a real .claude/skills/ folder.

Pattern 1: code-review Skill + GitHub MCP

The classic. A team-standardized review workflow lives in the project's .claude/skills/code-review/SKILL.md; the GitHub MCP server provides the I/O. The skill encodes your house style — comment density, when to suggest a refactor, when to insist on tests, what a "blocker" looks like. The MCP does the diff fetch, the comment post, the review submission. Adding a new convention to the team's review style is a one-line PR to the skill; nothing changes in the MCP layer.

Pattern 2: database-analyst Skill + Postgres MCP

This is where the Skill earns its keep. The Postgres MCP server alone will happily issue any SQL you give it. The Skill adds the guardrails: "never run DROP/TRUNCATE/ALTER", "always wrap unbounded queries with LIMIT 100", "run EXPLAIN first if the table is larger than 10M rows", "prefer the read replica connection over primary". The skill also references references/schema-overview.md — a hand-curated map of the data model — so Claude does not waste cycles re-deriving table relationships from information_schema. Teams running this pattern report 5-10x fewer dangerous queries, because the procedure is in the skill, not in the user's head.

Pattern 3: incident-response Skill + Sentry + GitHub MCP

The on-call's favorite. The skill triggers when someone says "investigate Sentry issue X" or pastes a Sentry URL. It pulls the issue and stack trace via the Sentry MCP, walks the stack to find the offending file, queries the GitHub MCP for the most recent commits that touched that file, identifies the regression candidate, and drafts a fix PR with the failing test and a TODO. The skill encodes your bisection heuristics; the two MCPs do the data fetch and the side effect. Sentry's own docs describe this loop ending in a one-shot draft PR.

Pattern 4: customer-support triage Skill + Slack + Linear MCP

For teams who run #support in Slack and ship tickets in Linear: a triage skill that watches a channel via the Slack MCP, classifies inbound messages (bug, feature request, configuration help), creates a Linear issue for the bug class with the Slack permalink in the description, posts an acknowledgement thread reply, and tags the on-call. One skill, two MCP servers, what used to be a four-step on-call playbook compressed into a single ask.

When do you use Skills, MCP, and when do you reach for subagents?

A three-question decision tree covers most cases:

• Does Claude need access to a system it cannot reach today? → MCP server.
• Do you keep re-explaining the same workflow to Claude across sessions? → Skill.
• Does the task need its own context window and tool budget — e.g. "read these 200 files and summarize"? → Subagent.

And often: all three. The incident-response pattern above uses two MCP servers, a Skill, and (if it's a big incident) spawns a subagent to chew through the commit history without polluting the main session's context.

For the deeper comparison between Skills, AGENTS.md, Cursor rules, and CLAUDE.md, see our configuration formats comparison and the dedicated AGENTS.md pillar.

The security conversation you cannot skip

MCP's threat model has matured in 2026 and the headline finding is uncomfortable. The MCPTox benchmark tested 45 live MCP servers and 353 real tools against poisoned descriptions and found that many popular agents had attack-success rates above 60%, with the worst at 72%.

The dominant class is tool poisoning: an attacker hides instructions inside tool metadata that the agent reads but the user does not see. The structural issue is a trust gap — tool descriptions are reviewed once when the client connects, but tool responses stream straight into the LLM's context with no equivalent check. The unguarded runtime channel is the attack surface.

What to do about it, in priority order:

1. Pin server versions. A server you trusted last week can ship a description change today. Pin the npm version, pin the container digest.
2. Scope with allowed-tools. A docs-formatting Skill should not hold the GitHub write tool. The frontmatter field is experimental but real.
3. Prefer first-party vendor servers. Sentry, Stripe, GitHub, and Linear sign and ship their own. A random community fork is the wider supply-chain surface.
4. Keep human-in-the-loop on irreversible side effects. Posting a Slack message, opening a PR, deleting an issue — these should still surface a confirmation in 2026. Auto-approve only read tools.
5. Audit at runtime, not just at connect-time. Log tool responses, run an LLM-based classifier over them looking for injected instructions, alert on anomalies.

Context budget: Skills are cheap, MCP is expensive

One last practitioner note. A typical Skill costs ~30-50 tokens of context until invoked. A typical 5-server MCP setup with 58 tools eats ~55,000 tokens of context before you have sent a single prompt, because every tool name, description, and parameter schema is loaded upfront. If your context window is feeling tight, your first move is to disable MCP servers you don't need this session, not to delete skills.

Frequently asked questions

Can a Skill call an MCP tool directly?

Yes. Reference the tool by its qualified name (for example, mcp__github__get_pull_request_files) in the Skill body, and list it in allowed-tools if you want it pre-approved. Claude will invoke the tool through the MCP client when it follows the skill's steps.

Do Skills work outside Claude Code?

Yes. The same SKILL.md works in Claude.ai, Claude Code, and the Claude API (upload via Files API, enable in the request). The format is also adopted by OpenAI Codex CLI, Cursor, Gemini CLI, and GitHub Copilot.

What happens if I name my Skill "claude-helper"?

It will be rejected. "claude" and "anthropic" are reserved words in the name field. Rename it — "helper" or "workspace-helper" is fine.

Should I write a custom MCP server or a Skill?

If the thing you want to extend is a static reference document or a multi-step playbook, write a Skill. If it is an external system Claude cannot reach today, write or install an MCP server. If you are wrapping an existing REST API, write the MCP server — that is exactly what the protocol is for.

How do I share a Skill with my team?

Drop it in .claude/skills/<name>/ at the repo root and commit. Every teammate who pulls the repo gets the skill on their next Claude Code session. For broader distribution, package it as a Claude Code plugin and register a marketplace with /plugin marketplace add.

Is MCP locked to Anthropic?

No. Anthropic donated the protocol to the new Agentic AI Foundation, and it is now implemented by Anthropic, OpenAI Agents SDK, Cursor, Cloudflare Agents, and Microsoft. The protocol is open and language-agnostic; servers exist in TypeScript, Python, Go, Rust, and others.

How do I debug a Skill that won't trigger?

Almost always the description field. Claude only sees that string when deciding whether to load the body. Start the description with "Use when…" and be concrete about the trigger phrase, file type, or repo signal. Run /plugin to confirm the skill is registered.

Where this fits in the Codersera stack

Skills and MCP are the two extension surfaces that make Claude Code feel like an extension of your engineering org, not a chatbot in a sidebar. If you're an engineering leader picking up Claude Code for the first time in 2026, our recommended onboarding sequence is: read the Claude Opus 4.7 pillar for model context, the AI coding agents pillar for the broader landscape, and the AGENTS.md pillar for the configuration format that complements Skills.

If you want senior engineers who can land this kind of integration work — Skill design, MCP server selection, secure rollout — Codersera vets remote developers for exactly this profile. We'll match you with engineers shipping production agent integrations today.