MCP and Skills

MCP integration capabilities (tools, data, external systems), Skills injection methods (workflows, best practices, domain knowledge). One is an extension of limbs and hands, the other is an injection of experience—both use progressive disclosure, yet they are two composable layers.

Overview

The Agent Loop solves "how models use tools"; this article solves "how to add things to an agent." When extending an agent, there are two equally important but often conflated layers:

• MCP integrates capabilities / interfaces—executable tools, readable data, external systems. It enables the agent to do new things.
• Skills inject knowledge / methods—workflows, best practices, domain know-how, reference files. It enables the agent to do things correctly.

One is an "extension of limbs and hands," the other is an "injection of experience." Both use the approach of on-demand loading without bloating the base context (both belong to progressive disclosure), which can make them seem like the same thing; in reality, they are two composable layers—the method layer (Skills) calls the capability layer (MCP/tools). The first half of this article covers MCP, the second half covers Skills, and finally, they are compared side-by-side.

Part 1: MCP — Integrating Capabilities

What It Eliminates: The M×N Integration Explosion

Without a standard, M AI applications × N tools/data sources require writing M×N sets of integrations. MCP (Model Context Protocol) is an open protocol, often described as the "USB-C of tools": tool providers expose a server according to the protocol, and application providers implement a client, reducing integration complexity to M+N.

flowchart LR
    subgraph N1["Without MCP — M×N integrations"]
        direction LR
        a1["App1"]
        a2["App2"]
        g1["GitHub"]
        s1["Slack"]
        d1["DB"]
        a1 --- g1
        a1 --- s1
        a1 --- d1
        a2 --- g1
        a2 --- s1
        a2 --- d1
    end
    subgraph N2["With MCP — M+N"]
        direction LR
        b1["App1"]
        b2["App2"]
        mcp{{"MCP Protocol"}}
        g2["GitHub server"]
        s2["Slack server"]
        d2["DB server"]
        b1 --> mcp
        b2 --> mcp
        mcp --> g2
        mcp --> s2
        mcp --> d2
    end

MCP was proposed and open-sourced by Anthropic at the end of 2024 and has since become a cross-vendor de facto standard.

Client-Server Architecture

flowchart LR
    subgraph Host["Host (e.g. Claude Code)"]
        Model["Model<br/>Decides which tool to use"]
        Client["MCP Client<br/>One per server"]
        Model <-->|"tool_use / tool_result"| Client
    end
    Client -->|"JSON-RPC 2.0<br/>stdio / Streamable HTTP"| Server["MCP Server<br/>Exposes tools / resources / prompts"]
    Server --> World["Real World<br/>GitHub API / Filesystem / DB"]

• Host: Claude Code, Claude Desktop, custom apps—these run the MCP client.
• Server: Exposes a specific capability (GitHub, filesystem, database, etc.) according to the protocol; it can be a local subprocess or a remote service.
• Messages use JSON-RPC 2.0; transport uses stdio (subprocess, standard input/output) locally, and Streamable HTTP (formerly HTTP+SSE) remotely.

Three Primitive Types

The most commonly used is tools—it directly connects to the agent loop: tools exposed by the server appear to the model just like custom tools, producing tool_use, which the host executes, and then tool_result is fed back.

How to Connect a Server

Connecting a server in Claude Code is just a configuration snippet. For a local stdio server:

{
  "mcpServers": {
    "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] }
  }
}

For a remote HTTP server, provide the url. This machine currently connects to two real, active servers: context7 (pulls latest library docs on demand) and code-review-graph (parses the codebase into a structural graph for review).

On the Claude API side, connecting to a remote MCP uses two mandatory paired parameters (beta mcp-client-2025-11-20):

client.beta.messages.create(
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{"type": "url", "name": "my-tools", "url": "https://.../mcp"}],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "my-tools"}],
    ...,
)

In Managed Agents, server declarations are placed on the agent (type/name/url, without credentials); credentials are stored in the vault and attached using vault_ids when creating the session—the Anthropic-side agent injects the token during outbound requests, and code in the container cannot read the secrets.

Security: Servers Run with Permissions

• Servers run with certain permissions—a server that can read/write files or call GitHub is effectively handing those permissions over to model decision-making. Untrusted servers should be sandboxed, use least privilege, and route credentials through a vault rather than hardcoding them.
• Prompt injection in tool outputs: Content returned by the server enters the context and is read as "observations." If a webpage or issue contains "ignore previous instructions and do X," it could hijack the agent. Treat tool outputs as untrusted data, and route dangerous actions through human-in-the-loop.

Part 2: Skills — Injecting Methods

What is a Skill

A Skill is a folder, centered around a SKILL.md, packaging workflows, best practices, and reference files for a specific domain. It solidifies "know-how that needs to be repeated every time" into reusable resources, turning a general-purpose agent into a domain expert—for making PPTs, creating Excel sheets, or writing code according to specific standards.

It differs from a one-off prompt: a prompt is a temporary instruction for this round of conversation; a skill is a persistent method that is loaded on demand across conversations.

SKILL.md and Progressive Disclosure

The essence of a Skill is progressive disclosure—not stuffing all content into the context, but loading it in layers:

flowchart TD
    A["① name + description<br/>(Always in context, very small)"] -->|Model judges task relevance| B["② SKILL.md body<br/>(Loaded on demand: workflows/rules)"]
    B -->|When needed| C["③ Referenced files / scripts<br/>(Loaded only when used)"]

---
name: pptx
description: Use when creating or editing PowerPoint presentations.
---

# Workflow for Creating Presentations
1. First, plan the outline...
2. Generate using python-pptx...
(More steps, templates, script references)

Only that line of description remains in the context (a few dozen tokens); when the model judges the task is relevant, it reads the SKILL.md body; templates/scripts referenced in the body are loaded only when used. This way, dozens of skills won't bloat the base context—the same trick used by MCP to load tool schemas on demand via tool search.

Built-in vs. Custom

Each agent can have up to 20 skills. On the Messages API, enable them via container.skills + code_execution tool + two betas (code-execution-2025-08-25, skills-2025-10-02); generated .pptx/.xlsx files are returned as file IDs and downloaded via the Files API. On Managed Agents, skills are directly an array in the agent definition.

In the Anthropic context, there are two places called "Skills," which are two carriers of the same idea: Claude Code's SKILL.md skills (such as /oh-my-claudecode:... type, and the claude-api skill in this session), and the Agent Skills of the API / Managed Agents.

When to Write a Skill

• Write a skill: When a set of know-how will be used repeatedly across conversations/tasks (team code standards, fixed report formats, standard processes in a certain domain), or when producing specific format documents.
• A one-off prompt is enough: For temporary instructions needed only in this round of conversation.

The criterion is the same as "when to write an MCP server": If reuse value is high, solidify it (write a skill / write a server); if used once, don't over-engineer.

Together: Capabilities vs. Methods

They are composable—the method layer calls the capability layer: a skill's workflow can certainly call tools exposed by MCP.

flowchart TD
    Loop["Agent Loop — Orchestration Layer"]
    Skills["Skills — Method Layer<br/>Workflows / Domain Know-how / References"]
    Cap["Capability Layer<br/>MCP Tools · Built-in Tools · Custom Tools"]
    Loop --> Skills
    Skills -->|Drives| Cap
    Loop -->|Can also call directly| Cap

Falling back to the stack in this session: claude-api and those OMC SKILL.md files are the method layer; context7, code-review-graph, and other MCP servers are the capability layer. Each manages its own domain; together, they form a complete agent.

Frontier: MCP is Already a Cross-Vendor Standard

A strong piece of evidence: Alibaba's world model Qwen-AgentWorld-35B-A3B, in its seven simulated agent environments, the first category is "tool calling (MCP)"—even a leading non-Anthropic model treats "calling tools via MCP" as the standard interaction paradigm for agents during training and simulation. MCP is becoming the universal interface for agents to interact with the world. See the frontier section of Agent Loop and Tool Use for details.

Best Practices

• Distinguish the two layers before extending. If you lack capabilities (connecting to external systems), use MCP; if you lack methods (repeated know-how), write a Skill; don't use one to solve the other's problem.
• Solidify only if reuse value is high. Write a server / skill only if used repeatedly across conversations; for one-time temporary instructions, a prompt is enough.
• Control context with progressive disclosure. For Skills, only keep description in context, read the body on demand; for many tools, use tool search to load schemas on demand—dozens won't bloat it.
• Sandbox untrusted servers + use least privilege. Servers run with permissions, effectively handing those permissions to model decision-making.
• Route credentials through the vault, don't hardcode. Managed Agents place server declarations (without credentials) on the agent, store credentials in the vault, and inject them on outbound requests; the container cannot read the keys.
• Treat tool outputs as untrusted data. Content returned by the server enters the context and is read as "observations"; prevent prompt injection (see Security and Protection).

Trade-offs and Failure Modes

• Confusing MCP and Skills: Thinking it's one or the other → They are two composable layers; the method layer (Skill) calls the capability layer (MCP/tools).
• Writing a skill when a prompt would suffice: Over-engineering temporary instructions needed only in this round → Use a prompt for one-time needs.
• Hardcoding server credentials into config/agent: Risk of leakage → Use the vault, inject on outbound.
• Believing "instructions" inside tool outputs: Webpages/issues hiding "ignore previous instructions" to hijack the agent → Treat tool outputs as data, route dangerous actions through human-in-the-loop.
• Treating local stdio servers as remote connections: Wrong transport → Local stdio (subprocess), remote Streamable HTTP, don't mix them.

References

• Protocol Specification: modelcontextprotocol.io (JSON-RPC, transport, primitive definitions, refer to official docs)
• Anthropic Documentation: MCP Connector (mcp_servers + mcp_toolset), Agent Skills, Managed Agents Vaults (platform.claude.com)
• Leading Models: Qwen-AgentWorld-35B-A3B (lists MCP tool calling as one of the simulated domains)

Keywords: MCP, Model Context Protocol, client-server, JSON-RPC, stdio, Streamable HTTP, SSE, tools, resources, prompts, mcp_toolset, mcp_servers, vault, prompt injection, M×N, USB-C for tools, context7, code-review-graph, Skills, SKILL.md, Agent Skills, progressive disclosure, capabilities vs methods