Skill or MCP server? Where the boundary actually is

Published 2026-05-11 by Owner

You want Claude Code to do something it doesn’t do well out of the box. You’ve heard about skills and MCP servers. Both are “ways to extend Claude Code.” So which do you reach for?

The confusion is understandable — the two features are adjacent in the docs and both feel like “customization.” But they operate at completely different layers, and mixing them up means you’ll build the wrong thing, then wonder why it doesn’t work.

The short version: skills shape model behavior; MCP servers add tool capabilities. That’s the whole distinction. Everything else follows from it.

Skills and MCP servers compose — you can have both active at once — but they solve different problems. Reaching for the wrong one wastes time.

What MCP servers actually do

MCP (Model Context Protocol) servers give Claude Code new tools to call. Tools in the Claude Code sense are callable functions — like read_file or run_bash_command, but for external systems.

Without an MCP server, Claude Code has no concept of your Postgres database. It can’t run queries. It can write SQL if you ask it to, but it can’t execute that SQL against your actual schema. An MCP server running a Postgres adapter changes that: it exposes a query_database tool that Claude can call with a SQL string and get results back. The model now has a data path into your system.

This is the pattern: MCP servers are how you give Claude Code access to things it has no built-in access to.

Postgres, MySQL, SQLite — a database MCP server
Linear, Jira, GitHub Issues — a project management MCP server
Your internal REST API — a custom MCP server wrapping your endpoints
Notion, Confluence, Obsidian — a knowledge base MCP server

The hallmark of “I need an MCP” is: I need Claude to read from or write to a system that exists outside the repo. If you find yourself thinking “Claude needs to be able to call X,” that’s an MCP problem.

Here’s what a minimal MCP server registration in Claude Code’s settings.json looks like for a Postgres adapter:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"],
      "env": {
        "PGPASSWORD": "your-password"
      }
    }
  }
}

Once registered, query_database (or whatever the server exposes) appears in Claude Code’s available tools. Claude can call it the same way it calls any built-in tool.

MCP servers come with operational weight. You need a server process running (local or remote), authentication configured, and the server registered in Claude Code’s config. If the server goes down, the tool call fails. That’s fine — it’s a real integration with a real system. Just know what you’re taking on.

What skills actually do

Skills are different. A skill is a markdown document that tells Claude how to think about and approach a task. It doesn’t add new tool capabilities; it shapes how Claude uses the capabilities it already has.

A skill might say: “When debugging a failing test, first reproduce the failure in isolation. Check the test’s setup and teardown before looking at the assertion. Look for shared state between tests before assuming the tested code is wrong.” None of this requires any tool Claude doesn’t already have — it’s guidance about how to reason, what to check first, and in what order.

Or a skill might define a workflow: “When reviewing a PR, run the tests first. Read the diff top-to-bottom once before leaving any comment. Check for missing error handling on every external call. Look for new dependencies and evaluate them.” This is pure discipline — the skill encodes the workflow so you don’t have to repeat it in every prompt.

The hallmark of “I need a skill” is: I want Claude to approach this category of task differently. Better methodology, more consistent process, awareness of project-specific patterns — none of that needs a new tool.

Skills are cheap to author. Write a markdown file, install it, and Claude Code loads it when that skill is invoked. No server process. No auth. No operational overhead. If the skill gives bad guidance, edit the file.

One thing people miss: a skill can change behavior that prompting alone won’t reliably change. If you add “always check for edge cases” to a prompt, Claude does it once for that prompt. If you encode “when debugging, always check for edge cases before touching the happy path” in a skill, it becomes the default approach every time that skill is active. The skill is persistent; the prompt is ephemeral.

This is especially useful for team workflows. A code-review skill that encodes your team’s review checklist — security, error handling, test coverage, API contract changes — runs the same checklist every time, not just when whoever is reviewing remembers to ask for it. The skill is the process, not a reminder to follow the process.

The hybrid case

The distinction gets interesting when you need both.

Imagine a review-pr-for-db-changes skill. The goal: when a PR modifies a migration file, verify that the migration is safe against the actual production schema before approving.

The skill provides judgment: run the tests, identify migration files, check for destructive operations (column drops, type changes), cross-reference against the current schema to verify compatibility, flag anything risky before approval. This is a workflow and a set of heuristics — exactly what a skill does well.

But the MCP server is what makes “cross-reference against the current schema” possible. The skill can say “call query_postgres to get the current column types for the affected table.” That tool call only exists because you’ve set up a Postgres MCP server. The skill provides the judgment about what to check and why; the MCP provides the data path to the actual schema.

Without the MCP, the skill can catch structural problems in the migration SQL itself, but it’s guessing about production state. Without the skill, the MCP can answer any query Claude thinks to ask, but you’re relying on Claude to know which questions to ask from scratch on every run.

Together: the skill knows what to do and when to call the MCP; the MCP makes that call yield real data.

This is the pattern for sophisticated integrations: a skill orchestrates a workflow and knows when to reach for MCP tools, while MCP servers provide the external data paths the skill needs. The two are orthogonal, not competing.

The review-pr-for-db-changes skill also illustrates something subtler: the skill is where domain knowledge lives. A junior engineer might not know to check whether a migration drops a non-nullable column before backfilling. That knowledge goes in the skill. The MCP just answers “what columns does this table have right now?” The judgment about whether that’s safe — that’s the skill’s job. You can swap out the Postgres MCP for a different database adapter without rewriting the skill’s logic.

Costs and friction, honestly compared

Skill authoring: Write markdown. If your project follows the Claude Code skill convention, create a SKILL.md file, describe what the skill does and how to invoke it, install it. Total setup time: 15–30 minutes for a well-thought-out workflow, less for something simple. Iteration is fast — edit the markdown and invoke the skill again. No downtime, no dependencies.

MCP server setup: Find or build a server for your system. Configure the server connection in Claude Code’s settings.json (server process, args, environment variables for auth). Test that tool calls work. If you’re building a custom server, add the time to implement the protocol. For off-the-shelf servers like the official Postgres or filesystem adapters, setup might take 30 minutes; for a custom server against your internal API, it might take a day. And you’re now running a process that needs to stay up.

Neither is “harder” in an absolute sense — they’re different problems with different scopes. A skill is a writing task. An MCP server is a software integration task.

The friction comparison matters for a common mistake: building an MCP server for a problem that’s actually a skill problem. If all you need is for Claude to follow a more disciplined debugging process, writing a 50-line SKILL.md will solve that. You do not need a server process for that.

The reverse mistake also happens: people write elaborate skills that try to reason about external state they don’t actually have access to. A skill can say “check the database schema” all day, but if there’s no MCP server providing database access, Claude will either hallucinate or tell you it can’t do the check. The skill’s instructions are only as good as the tools available to execute them.

A decision heuristic that holds up

Ask: does this require access to an external system that Claude doesn’t currently have?

If yes: MCP server. The capability you need doesn’t exist in Claude Code’s tool set — it needs to be added.

If no: skill. The capability exists (Claude can read files, run commands, write code). What’s missing is judgment, process, or domain-specific guidance. That’s what a skill provides.

A few concrete examples to stress-test the heuristic:

“I want Claude to query our production database” → MCP server. External system, no existing tool.
“I want Claude to file a Linear ticket when it finds a security issue” → MCP server. External system.
“I want Claude to follow a consistent process when investigating performance regressions” → skill. No new tool needed; better workflow discipline.
“I want Claude to always check for null pointer exceptions in code reviews” → skill. It already knows how to read code; it needs the habit.
“I want Claude to look up our internal runbook for an incident type and then follow it” → both. MCP to fetch the runbook from Confluence; skill to encode what to do once it has the runbook.

If you find yourself wanting both — external data access AND consistent workflow discipline around that access — write the skill first, then add the MCP server for the data paths the skill needs.

One thing worth noting: skills are also how you make an MCP tool useful reliably. An MCP server that exposes query_database is powerful, but Claude will use it inconsistently without guidance about when to call it and how to interpret the results. A skill wrapping that MCP tool turns “Claude can query the database” into “Claude follows a specific process when database state is relevant.” The MCP provides the capability; the skill makes it reliable.

Where this leaves you

MCP servers are the right answer when you’re integrating with something outside the repo. Skills are the right answer when you’re improving how Claude reasons about something it can already technically do.

For most teams, the skill layer fills out first. You identify the workflows where Claude’s default approach is inconsistent or wrong — incident debugging, PR review, writing API documentation — and encode them. This pays off immediately and the iteration cycle is short.

The MCP layer fills in later, when you hit specific integration needs. You want Claude to file a Linear ticket when it finds a bug. You want it to query the production database to verify migration safety. You want it to look up your internal runbooks when responding to an alert. Each of these requires a real tool call to a real system — that’s what MCP servers are for.

The Claude Code ecosystem is building out both directions. Server directories are growing — there are now off-the-shelf MCP servers for Postgres, SQLite, GitHub, Linear, Slack, and most major developer tools. Skill authoring is getting more formalized as teams discover that consistent AI workflows are worth encoding.

Neither is going away, and neither replaces the other. They operate at different layers and solve different problems. Getting the distinction right means you spend your time building the right thing — and not wondering why a markdown file isn’t connecting to your database, or why your MCP server setup still isn’t making Claude review PRs the way you want.