The Specific Situation

You see both “skills” and “MCP servers” mentioned in Claude Code documentation. Your project needs Claude to query a PostgreSQL database, follow specific query patterns, and generate reports. Should you write a skill, set up an MCP server, or both? The confusion stems from overlap in descriptions – both “extend what Claude can do.” But they extend different things in different ways.

Technical Foundation

Claude Code Skills are instruction files (SKILL.md) that tell Claude how to do things. They contain procedures, checklists, conventions, and workflow steps. Skills are loaded as conversation context – they influence Claude’s behavior through natural language instructions. They do not add new API connections or external tool capabilities.

MCP Servers (Model Context Protocol) provide Claude with access to external systems. An MCP server exposes tools (functions Claude can call), resources (data Claude can read), and prompts (templated instructions). MCP servers run as separate processes, communicate via JSON-RPC over stdio or HTTP, and give Claude capabilities it otherwise would not have – like querying a database, calling a third-party API, or accessing a file system on a remote machine.

The boundary is clear: Skills = instructions (what to do), MCP = capabilities (how to access).

The Working SKILL.md

Combined skill + MCP pattern for database reporting:

---
name: db-reporter
description: >
  Generate database reports following team query patterns. Use when
  creating performance reports, audit queries, or data exports.
  Requires the postgres MCP server to be configured.
allowed-tools: mcp__postgres__query Read
---

# Database Report Generator

## Prerequisites
The postgres MCP server must be running and configured in
.claude/settings.json with access to the reporting database.

## Query Patterns (MANDATORY)
All queries generated by this skill MUST follow these rules:
1. Always include a WHERE clause with a date range filter
2. Never SELECT * — enumerate specific columns
3. Use CTEs (WITH clauses) for complex queries, not nested subqueries
4. Include LIMIT 1000 on exploratory queries
5. Add EXPLAIN ANALYZE prefix when query is new (remove for production)
6. Wrap financial amounts in ROUND(amount, 2)

## Report Types

### Performance Report
Metrics: p50/p95/p99 response times, error rate, throughput
Group by: endpoint, time_bucket (1h intervals)
Filter: last 7 days by default
Output: JSON to `reports/perf-{date}.json`

### Audit Report
Metrics: login attempts (success/failure), permission changes, data access
Group by: user_id, action_type, hour
Filter: last 24 hours for daily audit
Output: JSON to `reports/audit-{date}.json`

### Data Export
User-specified query with mandatory LIMIT
Output: CSV to `exports/{name}-{date}.csv`
Include row count and column headers in output

## Schema Reference
Read the database schema before generating queries:
- Use the postgres MCP server's `list_tables` tool
- Then `describe_table` for the specific tables needed
- Cache schema in `data/db-schema-cache.json` to avoid repeated lookups

Where MCP Servers Win

1. External API and database access. MCP servers connect Claude to PostgreSQL, GitHub, Slack, Jira, Google Drive, and any system with an API. Skills cannot make network calls or access external systems directly – they rely on Bash commands or pre-approved tools. If your workflow requires querying a database, MCP servers provide the cleanest integration.

2. Typed tool interfaces. MCP tools have defined input schemas (JSON Schema) that Claude uses for structured function calling. This is more reliable than a skill instructing Claude to “run this curl command” – the MCP tool validates inputs before execution.

3. Resource exposure. MCP servers can expose resources (database tables, API documentation, configuration) that Claude reads without executing commands. This is read-only access with no side effects, useful for reference data that changes frequently.

Where Claude Code Skills Win

1. Procedural workflows. Skills encode multi-step procedures with conditionals, checklists, and decision trees. MCP servers expose individual tools – they do not encode the workflow for using those tools. A skill says “query the orders table, filter by date, join with customers, calculate retention rate.” An MCP server just provides the query tool.

2. No infrastructure. Skills are markdown files. MCP servers require running a separate process, configuring connection strings, and managing authentication. For teams that need quick workflow automation without DevOps overhead, skills are immediately usable.

3. Context efficiency. Skills use progressive disclosure (description, body, references). MCP tool descriptions are loaded into context for every available tool, every turn. A project with 5 MCP servers exposing 40 tools pays a constant context cost for all 40 tool descriptions.

Complementary Pattern

The most effective architecture uses both. MCP servers provide the capability (database access, API integration). Skills provide the workflow (query patterns, output formats, validation rules). The skill’s allowed-tools field pre-approves the MCP tools it needs: allowed-tools: mcp__postgres__query mcp__github__create_pr.

User request: "Generate this week's performance report"
  → Skill loads: db-reporter (procedures, query patterns, output format)
  → MCP provides: postgres.query tool (database access)
  → Result: Correct query following team patterns, output in expected format

Without the skill, Claude would have database access but no guidance on query patterns. Without the MCP server, Claude would have the patterns but no database access.

Common Problems and Fixes

MCP tool called without skill guidance produces bad queries. Claude can call postgres.query with any SQL, including SELECT * with no LIMIT on a 10M-row table. The skill provides guardrails: mandatory WHERE clause, LIMIT, specific columns. Always pair database MCP servers with query convention skills.

Skill references MCP tool that is not configured. The skill uses allowed-tools: mcp__postgres__query but the MCP server is not running. Add a prerequisite check: “Verify the postgres MCP server is configured by checking .claude/settings.json for mcp_servers.postgres.”

Too many MCP tools inflate context. Each MCP tool description costs context tokens on every turn. If you have 40 tools but a skill only needs 3, the other 37 are wasted context. Consider running focused MCP servers with fewer tools rather than one server with everything.

Production Gotchas

MCP servers run with the permissions of the user who started them. A PostgreSQL MCP server with a read-write connection string lets Claude execute INSERT, UPDATE, and DELETE statements unless you restrict the database user’s permissions. Always use read-only database credentials for reporting MCP servers.

Skills and MCP tools have different persistence models. Skill instructions persist in the conversation (and survive compaction up to 5,000 tokens). MCP tool outputs are single-turn – Claude sees the result once and must reference it in future turns from memory or by re-querying.

Checklist