MCP vs Agent Skills: What's the Difference and When to Use Each

Two standards, different problems

If you work with AI coding tools, you've probably encountered both MCP (Model Context Protocol) and Agent Skills. They're often mentioned together, and many tools support both. But they solve fundamentally different problems, and understanding the distinction helps you choose the right approach for each use case.

The short version: MCP gives AI tools access to external systems (databases, APIs, browsers). Agent Skills give AI tools procedural knowledge (how to review code, write tests, generate documentation).

MCP is about capabilities. Agent Skills are about expertise.

What is MCP?

The Model Context Protocol is an open standard for connecting AI assistants to external tools and data sources. An MCP server exposes a set of tools — defined operations that the AI can invoke. When the AI needs to do something it can't do with text alone, it calls an MCP tool.

Examples of what MCP enables:

• Query a database — the AI sends SQL through an MCP tool and gets results back
• Control a browser — navigate pages, click buttons, take screenshots via Playwright
• Call external APIs — make HTTP requests, authenticate, parse responses
• Read files from a specific system — access Notion pages, Google Docs, Jira tickets
• Run shell commands — execute scripts, run tests, manage processes

Each MCP server is a running process (local or remote) that the AI communicates with over a defined protocol. The server handles execution, authentication, and error handling. The AI just calls the tool and gets a result.

For a deeper introduction, see Getting Started with MCP Servers.

What are Agent Skills?

Agent Skills are Markdown-based instruction sets that give AI tools procedural knowledge and specialized workflows. A skill is a directory containing a SKILL.md file plus optional supporting resources (scripts, templates, reference files).

Examples of what Agent Skills enable:

• Structured code review — a defined process with severity levels, output format, and specific checks
• Documentation generation — a workflow that reads source code, follows a template, and produces consistent docs
• Security auditing — a checklist-based assessment covering OWASP Top 10 with remediation guidance
• Project setup — steps to scaffold a new project with all conventions and configurations

Skills are text-based. They don't execute code or connect to external systems — they teach the AI how to think about a task. The AI loads the skill's instructions and follows them when the task is relevant.

For more on the specification, see The Agent Skills Specification, Explained.

Key differences

| | MCP | Agent Skills | |---|---|---| | What it provides | External capabilities (tools the AI can call) | Internal knowledge (instructions the AI follows) | | Format | Running server process with defined API | Markdown files with YAML frontmatter | | Execution | Server-side: the MCP server runs code | Client-side: the AI interprets instructions | | Example | "Run this SQL query against the database" | "When reviewing code, check for these 10 security patterns" | | Requires | A running server (local process or remote URL) | A file in the right directory — nothing to run | | State | Can maintain state (connections, sessions) | Stateless — just text loaded into context | | Discovery | Configured per-project in .mcp.json or equivalent | Auto-discovered from .agents/skills/ directory | | Portability | Server-specific (though the protocol is standard) | Fully portable across 40+ tools |

When to use MCP

Use MCP when your AI tool needs to interact with an external system.

Database access

You want the AI to query your database, inspect schemas, or write migrations based on real data. An MCP server connects the AI to your database securely, with appropriate access controls.

Browser automation

You want the AI to test a web UI, scrape a page, or verify that a deployed change looks correct. The Playwright MCP server gives the AI browser control.

Third-party integrations

You want the AI to read Jira tickets, update Notion docs, create GitHub issues, or send Slack messages. Each integration has its own MCP server.

System operations

You want the AI to run tests, check deployment status, or interact with cloud infrastructure. MCP servers can wrap any CLI tool or API.

The pattern: MCP is the right choice when the AI needs to do something in the real world, not just reason about it.

When to use Agent Skills

Use Agent Skills when your AI tool needs to follow a specific process or apply specialized knowledge.

Structured workflows

You want the AI to review code using your team's specific process: check for security issues first, then correctness, then style. A skill defines the exact steps and expected output format.

Reusable expertise

You've developed expertise in writing Terraform modules, designing APIs, or conducting security audits. A skill packages that expertise into a format any AI tool can use.

Team conventions

You want every developer on your team to get the same quality of code review, documentation, or test generation. Skills standardize the process across tools and team members.

Knowledge-intensive tasks

You want the AI to follow a complex process that requires domain knowledge: compliance checking, threat modeling, or architecture review. Skills provide the checklist, criteria, and decision framework.

The pattern: Agent Skills are the right choice when the AI needs to think about something in a specific way, not interact with external systems.

Using them together

MCP and Agent Skills are complementary, not competing. The most powerful setups combine both.

Example: Security audit with database access

• A security auditor skill defines the OWASP Top 10 checklist, severity levels, output format, and remediation patterns
• A database MCP server lets the AI check actual query patterns, inspect access controls, and verify that parameterized queries are used correctly
• A Playwright MCP server lets the AI test for XSS by actually rendering pages with malicious input

The skill provides the expertise (what to check, how to prioritize, how to report). The MCP servers provide the capabilities (access to the database and browser). Together, they enable an audit that's both thorough and grounded in reality.

Example: Documentation generation with API access

• A documentation skill defines the format, sections, and writing standards
• An MCP server connects to your running API, making real requests to verify endpoint behavior
• The AI produces documentation that's been validated against the actual API, not just the source code

Example: Test writing with coverage data

• A test writing skill defines how to structure tests, what patterns to follow, and what edge cases to cover
• An MCP server runs the existing test suite and reports coverage
• The AI writes tests that target uncovered code paths, guided by both the skill's methodology and the coverage data

How Agent Shelf connects both

Agent Shelf is a registry for agent definitions — which are structured like Agent Skills with metadata for discovery, versioning, and distribution. Many agents on the registry reference MCP servers they work well with. When you initiate an agent, the AgentShelf skill detects referenced MCP servers and helps you configure them.

The AgentShelf MCP server itself is an example of the two standards working together: it's an MCP server that helps you discover and install Agent Skills.

Quick decision guide

"I want my AI to query my database" → MCP

"I want my AI to follow a specific code review process" → Agent Skill

"I want my AI to write Terraform that follows our standards" → Agent Skill (for standards) + MCP (if it needs to check existing infrastructure state)

"I want my AI to test my web app" → MCP (for browser control) + Agent Skill (for test methodology)

"I want my AI to generate API docs" → Agent Skill (for doc format and standards)

"I want my AI to find and install other agents" → MCP (the AgentShelf MCP server)

Learn more

• Getting Started with MCP Servers — practical setup guide
• 10 MCP Servers Every Developer Should Know — curated list with configs
• The Agent Skills Specification, Explained — how the spec works
• How to Write Effective Agent Definitions — writing great agents