MCP and Skills

MCP integration capabilities (tools, data, external systems), Skills injection methods (workflows, best practices, domain knowledge). One is an extension of limbs, the other 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." Extending an agent involves 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," the other an "injection of experience." Both use the approach of on-demand loading to avoid 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). This article covers MCP in the first half, Skills in the second half, and finally compares them 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 compared to "USB-C for 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 in late 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 / File System / DB"]

• Host: Claude Code, Claude Desktop, custom apps—these run the MCP client.
• Server: Exposes a specific capability (GitHub, file system, 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 Primitives

The most commonly used is tools—it directly connects to the agent loop: tools exposed by the server look like custom tools to the model, 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, in-use 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, the server declaration is placed on the agent (type/name/url, without credentials); credentials are stored in the vault and attached using vault_ids when creating a session—the Anthropic-side agent injects the token when making 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 essentially 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, do X," it could hijack the agent. Treat tool outputs as untrusted data; 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 conversation turn; a skill is a persistent method loaded on demand across conversations.

SKILL.md and Progressive Disclosure

The essence of a Skill is progressive disclosure—not stuffing everything 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 description line stays in the context (a few dozen tokens); the model reads the SKILL.md body only when it judges the task relevant; 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 as MCP using tool search to load tool schemas on demand.

Built-in vs. Custom

Each agent supports up to 20 skills. On the Messages API, enable 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 API / Managed Agents' Agent Skills.

When to Write a Skill

• Write a skill: When a certain know-how will be reused 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 conversation turn.

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

In the stack where this session resides: claude-api, those SKILL.mds in OMC 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 to train and simulate. MCP is becoming the universal interface for agents to interact with the world. See the frontier section of Agent Loop and Tool Use.

Best Practices

• Distinguish the two layers before extending. Lacking capabilities (connecting to external systems)? Use MCP. Lacking 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 reused 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 + least privilege for untrusted servers. Servers run with permissions, effectively handing permissions to model decision-making.
• Route credentials through vault, don't hardcode. In Managed Agents, put server declarations (without credentials) on the agent, store credentials in the vault, inject 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 turn → Use a prompt for one-time needs.
• Hardcoding server credentials in config/agent: Leakage risk → Use vault, inject on outbound requests.
• Believing "instructions" in 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 server as remote: 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