DEV Community: Zhengxin

Claude Code Skills Deep Dive (1): From a Markdown File to a Portable Folder

Zhengxin — Thu, 05 Nov 2026 02:09:39 +0000

TL;DR: The Agent Skills format defines a portable folder: SKILL.md supplies discovery metadata and core instructions; references hold knowledge to read when needed; scripts perform deterministic operations; and assets provide templates and materials. Claude Code accepts that core, then adds product-specific invocation, execution, permission, and path behavior. Write the portable core first, and be explicit about which behavior depends on Claude Code.

In Part 0, we placed Skills in the capability stack: they participate in selection somewhat like tools, but activation loads operational knowledge rather than entering a separate atomic executor.

Now look at the filesystem. Why is a Skill an entire folder instead of a single deploy.md file?

One Markdown file soon becomes three kinds of material

Start with a release-check Skill containing four steps:

1. Inspect the working tree.
2. Run tests.
3. Check the changelog.
4. Summarize risks.

As the workflow matures, it needs a detailed versioning policy to consult, a version-number validator to run, and a release-report template to fill in. Putting all three into the same Markdown file would load policy, code, and template alongside the core procedure. It would also blur the distinction between instructions needed every time and material needed only for a particular branch of the work.

The Agent Skills specification therefore defines a Skill as a directory with SKILL.md at its entry point, not merely as a Markdown document:

release-check/
├── SKILL.md
├── scripts/
│   └── validate-version.sh
├── references/
│   └── version-policy.md
└── assets/
    └── release-report.md

These locations express different roles:

Location	Role	How Claude uses it
`SKILL.md` frontmatter	Capability index	Decides whether the Skill is relevant
`SKILL.md` body	Core instructions	Enters context when the Skill is activated
`references/`	On-demand knowledge	Read when a relevant question arises
`scripts/`	Deterministic operations	Run when needed, without loading the entire source into context
`assets/`	Templates and resources	Used to create or transform the final output

The folder is both a capability manual and a bundle of working materials.

`SKILL.md` is an entry point, not a warehouse

The entry file does at least three jobs: its metadata says what the Skill is and when to use it; its body explains what to do after activation; and it points Claude toward supporting files at the right moment.

The third job is easy to miss. Merely placing version-policy.md in references/ does not tell Claude why or when to read it. The entry file should supply conditions:

## Supporting resources

- When evaluating a version number, read `references/version-policy.md`.
- For a mechanical format check, run `scripts/validate-version.sh`.
- For the final report, use `assets/release-report.md`.

This is navigation, not a redundant directory listing. Progressive disclosure works only if Claude can find the next resource when it becomes relevant. Think of SKILL.md as a map: the description tells Claude when to open it, the body identifies the main route, and supporting files are branches that need not be copied into the map itself. Too little guidance makes the map unusable; too much detail defeats the purpose of loading information in stages.

What the open format standardizes

The open specification requires YAML frontmatter followed by a Markdown body. A minimal portable core looks like this:

---
name: release-check
description: Check whether a version is ready to release; use when preparing a release.
---

Here name gives the folder a stable identity, description says both what it does and when to use it, and the Markdown body stores the instructions. scripts/, references/, and assets/ are optional conventional locations. The specification also defines optional metadata such as license, compatibility, and an extensible metadata map; allowed-tools is experimental.

The format does not standardize Claude Code's UI, subagent types, or session lifecycle. Another agent can understand the same folder's instructions, but each host decides where to discover it, how to show the metadata to the model, how to activate it, where a script runs, and what to do with the result. This is the boundary between a format standard and a product runtime.

What Claude Code adds

Claude Code plugs Skills into its commands, tools, subagents, hooks, and permission system. Its frontmatter can therefore express additional, product-specific behavior. Group those extensions by the question they answer:

Question	Claude Code-specific direction
Who can invoke it?	User invocation, model invocation, and visibility
Where does it run?	Current conversation or a forked subagent
What input does it receive?	Arguments and dynamic context
What may it do?	Tool pre-approval, hooks, and other execution controls
Where is it relevant?	Path-based conditions

A deployment Skill might be user-invoked only; a research Skill might run in a separate subagent context; a frontend Skill might apply only to particular paths. These features are useful, but they are not promises made by every Agent Skills-compatible host. The same file effectively contains two layers:

Portable Agent Skills core
  name · description · instructions · supporting files
        ↓ interpreted by a host
Claude Code extensions
  invocation · fork · paths · hooks · permissions · dynamic context

When authoring a Skill, know which layer a behavior depends on. “Works in Claude Code” should not silently become “guaranteed by the Agent Skills standard.” The Claude Code Skills guide documents its own extensions; the open specification defines the portable baseline.

The apparently contradictory `name` field

The open specification requires name and expects it to match the parent directory. Claude Code can derive a local Skill's command identity from that directory, so its own documentation allows the frontmatter name to be omitted in some local cases.

These are answers to different questions. The open format asks how a folder preserves a verifiable identity outside the current host. Claude Code asks which /skill-name a user types when the local directory is already known. A personal, Claude Code-only Skill can rely on directory inference. For a Skill intended to travel between clients, explicitly writing a standards-compliant name and description is the safer choice.

The same principle applies to other extensions: write the portable core explicitly, add host-specific controls where useful, and do not make an extension carry the whole meaning of the workflow. For example, “wait for user confirmation before deployment” belongs in the body instructions, not solely in a Claude Code setting that prevents automatic invocation. The setting is an extra safeguard; the instructions preserve the workflow's intent.

A script does not turn a Skill into a tool

Bundling a script does not erase the Skill/tool boundary. A host-registered tool has a defined invocation interface, permission identity, and result protocol. A script inside a Skill is implementation material carried by that Skill. Claude still follows the instructions to decide when to run it through an existing execution capability:

Skill instructions: “Check the version file first.”
        ↓
Existing execution capability: Bash / code execution
        ↓
Bundled script: scripts/validate-version.sh

Scripts suit steps with clear inputs and repeatable outputs. Instructions suit contextual judgment, exceptions, and orchestration. Leaving every deterministic check in natural language asks the model to reinterpret it each time. Hard-coding the entire workflow into one script, however, sacrifices Claude's ability to handle context and exceptions. The Skill folder lets the two approaches work together.

An asset is not a reference

Both references/ and assets/ might contain Markdown, JSON, images, or templates. Their distinction is purpose, not extension: a reference is read to inform Claude's judgment; an asset is used to make the final deliverable. An API specification belongs with references, while a report template belongs with assets.

This distinction helps with review. Changing a reference may change Claude's decisions. Changing an asset mainly changes the output's form. Changing a script may change a deterministic operation. Changing SKILL.md can change discovery and the overall workflow. A folder gives us clearer change boundaries than a single versioned prompt.

Why custom commands converged with Skills

An older custom command could already expose Markdown as /deploy: the user could save a prompt and invoke it repeatedly. Skills add a discoverable description, a folder of supporting files, and richer frontmatter for invocation and execution. Claude Code still supports older command files, but recommends Skills for new work.

This is more than renaming slash commands. It moves from “the user expands a stored prompt” toward “the user or model can discover a capability bundle.” Still, not every built-in command is a Skill: some commands trigger product-internal behavior, while a bundled Skill primarily supplies instructions and orchestrates tools. Sharing a /name entry point does not imply identical execution semantics.

The open standard makes the bundle recognizable; the product runtime makes it participate in a session. Both layers matter, and they should not be confused.

The next article follows metadata, instructions, and resources through their different loading times to examine the context-cost trade-off behind progressive disclosure.

References

Claude Code Skills Deep Dive (0): From Repeated Prompts to Callable Capabilities

Zhengxin — Wed, 04 Nov 2026 02:09:41 +0000

TL;DR: A Skill packages instructions, checklists, and multi-step workflows into an on-demand capability. Claude can discover it from its name and description, load the full instructions when they matter, and then use existing tools to do the work. A Skill participates in capability selection, but it is not a new atomic executor.

When preparing a release, you may find yourself telling Claude the same thing again:

First check the working tree, then run the tests, prepare a changelog,
verify the version number, and list the files that would be released.
Do not actually publish anything until I confirm.

This is not a fact that applies to every task in a project, so putting it in CLAUDE.md would make unrelated sessions carry an occasional procedure. Nor is it one atomic tool action: it involves checking Git state, running tests, reading a changelog, and summarizing risks in a deliberate order. It is a reusable way of working that otherwise has to be restated in each conversation.

That is the problem a Skill solves: how can operational knowledge persist without entering every task's context?

Save the workflow as a folder

Put the release procedure in a directory called release-check:

release-check/
└── SKILL.md

The file has two parts:

---
name: release-check
description: "Check whether a version is ready to release; use when preparing a release."
---

1. Inspect the working tree.
2. Run tests and a build.
3. Check the version number and changelog.
4. Summarize risks and wait for user confirmation.

The frontmatter fields name and description are metadata: a compact index entry that helps Claude recognize when this capability is relevant. The Markdown after the frontmatter is the instructions: the actual workflow Claude follows when the Skill is used. The Agent Skills specification defines this basic directory-and-SKILL.md shape; Claude Code's Skills guide explains how Claude Code discovers and invokes it.

The distinction is about timing. The description can be available for selection without loading the entire procedure. Once the task matches, Claude reads the full Skill body. Supporting files can be opened later, only if needed. This staged approach is called progressive disclosure. It keeps a large library of Skills practical, although metadata itself still has a context cost—descriptions should be useful and concise.

Selection resembles tool selection—but execution does not

If the user asks, “Is this version ready to release?”, Claude can decide whether release-check matches the request. The user can also invoke it explicitly with /release-check. This resembles tool selection in one respect: the model sees a capability's name and purpose, then decides when it applies.

It does not make a Skill the same thing as a tool. A tool has an executable operation behind it: Read reads a file; Bash runs a command. A tool call goes to a runtime and returns a result. Loading release-check instead gives Claude a set of instructions. Claude still uses existing tools to inspect the repository, run tests, and read the changelog. The Skill governs sequence, judgment, and stopping conditions; the tools perform the individual actions.

That is also why a Skill is not merely another name for CLAUDE.md. The latter carries standing project guidance into a session. A Skill is a discoverable, reusable candidate whose detailed instructions are loaded when relevant.

Tools turn “I can describe an action” into “I can perform an action.” Skills organize those actions into a reliable method for a recurring class of work.

The folder can carry more than instructions

Four Markdown steps are already more reusable than a prompt pasted into chat. But the directory can also contain supporting resources:

release-check/
├── SKILL.md
├── references/version-policy.md
├── scripts/validate-version.sh
└── assets/release-report.md

references/version-policy.md records the project's versioning rules. Claude reads it when deciding whether a change warrants a major release, not during every task. scripts/validate-version.sh turns a deterministic format check into executable logic instead of asking the model to improvise that check each time. assets/release-report.md gives the final report a consistent template.

The main instructions answer how to carry out this task now. A reference file supplies what the agent should know when a particular question arises. Both can enter context on demand, but they serve different purposes. The Skills guide documents supporting files and scripts; the next article in this series will look more closely at the folder format.

What happens after installation?

Several questions remain:

Discovery: How does Claude know this Skill exists?
Activation: Is typing /release-check the same path as Claude choosing it from the description?
Execution: Do the instructions run in the current conversation, or can they be delegated to a separate agent that returns only a summary?
Governance: Who can distribute the Skill, invoke it, and authorize the tools it uses?

These questions lead to a broader design rule: stable facts belong in standing guidance, atomic actions belong in tools, and reusable operational knowledge belongs in Skills. The series will reach that boundary in its conclusion. First, it will follow the lifecycle of a Skill like release-check, rather than translating documentation field by field.

Three layers, three costs

The folder structure is not merely a way to organize files. It determines when each piece becomes visible:

Layer	When it enters context	`release-check` example
Metadata	During capability discovery	`name`, `description`
`SKILL.md` body	When the Skill is activated	The four-step procedure
Supporting resources	When needed	Version policy, validator, report template

If the description is vague, Claude may never think to use the Skill for a release request. If it is bloated, every capability-discovery step carries unnecessary text. If the main body contains every detail, one activation loads too much. If no instruction points Claude to a reference file, that file may never be read. And if a deterministic check remains prose when it could be a script, the model has to reconstruct the same decision each time.

The next article examines which parts of this folder are defined by the open Agent Skills format and which behaviors are specific to Claude Code.

References

Claude Code MCP Deep Dive (9): Where MCP Ends and Skills, Tools, and Plugins Begin

Zhengxin — Mon, 02 Nov 2026 02:01:01 +0000

TL;DR: Use a script bundled with a Skill for private, deterministic logic. Use an existing local tool or executable for reusable work that does not need a separate integration. Reach for MCP when the capability belongs to another process or service. Put multiple related components into a plugin when you need a versioned, shareable installation unit. And when designing MCP servers, choose their boundaries with trust and administration in mind.

In Part 8, Claude Code could act as both an MCP client and an MCP server. That closes the mechanism-level loop: configuration, handshake, transport, tool exposure, permissions, authentication, resources, elicitation, and finally the reversal of roles.

This final installment asks a more practical question: when a new capability is needed, should MCP be part of the solution at all?

Start with the boundary, not the acronym

The decision tree from the companion Skills research series can be summarized like this:

Does the model need a new atomic action?
  ├─ Private, deterministic logic for one Skill → bundled script
  ├─ Reusable, local action                → existing tool / executable
  └─ External system or independent process → MCP tool

This is a design heuristic, not a rule enforced by Claude Code. The dividing questions are: who else needs this action, and must it run independently of Claude Code? Claude Code's Skills documentation explicitly supports helper scripts inside a Skill directory, while its MCP documentation covers connections to external tools, databases, and APIs.

A bundled script, a local tool, or an MCP server?

Suppose a Skill needs to validate version strings according to one project's conventions. If the check has no useful identity outside that Skill, make it a small bundled script and let the Skill's instructions decide when to run it. Turning it into a general-purpose tool—or an MCP server—would add an interface and maintenance burden without adding a meaningful boundary.

Now suppose many unrelated tasks need the same local operation. If it is still just a local executable, with no separate service or authentication lifecycle, an existing tool surface can invoke it. MCP is not automatically better merely because the action is reusable.

The stronger MCP case is an action whose natural home is another process or service. The Jira example from Part 1 fits: the data lives in somebody else's system, access follows that system's authorization rules, and the available operations can evolve independently. An MCP server gives that integration a defined discovery and invocation boundary instead of making Claude assemble ad hoc shell commands each time.

That boundary has concrete consequences. Part 4 followed the tool schema into Claude Code's exposed tool list; Part 5 examined permission rules; and Part 6 traced authentication. A shell script can certainly call an external API, but it does not thereby acquire MCP's standardized tool discovery, schemas, and client/server lifecycle. Those concerns would have to be handled separately.

One new server, or one more tool on an existing server?

Once several MCP servers are installed, a subtler choice appears: should a new operation go into an existing server, or should it live behind a new one?

Claude Code does not make that organizational decision. It connects to servers and exposes what they provide; server authors decide how many tools each server contains. But the boundary is visible to users. Operations that belong to the same internal system and are usually enabled, disabled, and maintained together may be easier to administer in one server. Operations with materially different trust requirements—say, read-only search versus changes to production data—may deserve separate servers.

This is not a claim that server separation alone makes a dangerous operation safe. Tool-level permissions and the server's own authorization still matter. Rather, separation gives administrators a cleaner unit for configuration and server-level policy. The trade-off is between a convenient shared installation and finer isolation.

Many servers: should they become a plugin?

A plugin is not another behavioral layer that replaces Skills or MCP. According to the Claude Code plugin overview, it packages components such as Skills, agents, hooks, and MCP servers into one installable unit. The MCP guide also describes how plugin-provided servers are started when the plugin is enabled.

Imagine a team that needs the same internal issue tracker, documentation service, and deployment integration, plus Skills explaining how to use them together. Rather than asking every teammate to recreate the setup in personal configuration or each repository's .mcp.json, a plugin can distribute and version the collection as one unit.

The same boundary test applies here: if one project needs the configuration and no shared release process is needed, keep it in project or personal configuration. If multiple repositories or teammates need the same curated collection and updates, a plugin becomes useful. Packaging is about distribution and lifecycle, not about making an MCP tool more powerful.

Closing the series

The opening distinction was: a Skill tells Claude how to do something; MCP gives it access to something it can do. Across this series, we saw how a configuration becomes a connection, how an external tool appears in the tool list, how permissions and authentication shape trust, how resources and elicitation extend the interaction, and how Claude Code can itself become a server.

Together, these mechanisms answer one question: when the model needs an action it did not ship with, where should that action live, how should it enter the loop, and who should be allowed to trust it?

References

Claude Code MCP Deep Dive (8): From MCP Client to MCP Server

Zhengxin — Fri, 30 Oct 2026 02:24:06 +0000

TL;DR: The first seven articles treated Claude Code as an MCP client connecting to someone else's servers. Claude Code can also run in the opposite role. claude mcp serve starts a local stdio MCP server so another MCP client can discover and call capabilities exposed by Claude Code. The direction changes, but the protocol still uses the familiar tools/list and tools/call boundary.

After Part 7 covered resources and elicitation, it is time to reverse the connection. In Part 1, we separated the host, client, and server roles. For most of this series Claude Code has been the client: it connects to an external server, discovers what that server offers, and makes those capabilities available in its own agent loop. Now turn the picture around. Another application can connect to Claude Code as a server.

This is not just a theoretical reading of the protocol. Claude Code's current documentation gives the command:

claude mcp serve

It starts Claude Code as a stdio MCP server, meaning the calling application launches it as a local subprocess and communicates over standard input and output. That is the same transport pattern we examined in Part 3, but with Claude Code on the server side of the pipe.

One tool definition, another exit

Inside Claude Code, a tool has a name, a description, an input schema, and an implementation. During an ordinary conversation, the agent loop presents those definitions to the model and validates the model's arguments before executing a selected tool. As an MCP server, Claude Code can adapt the relevant definitions to the protocol's tool listing format instead.

The source path examined for this series does that conversion at the server entry point. When an external client asks for tools/list, Claude Code enumerates the tools it exposes and converts their input schemas to JSON Schema. When the client sends tools/call, Claude Code locates the requested implementation, checks that it is available, validates the arguments, runs it, and packages the result for the MCP response.

Conceptually, the two directions look like this:

Claude Code as client:
  Claude Code → external MCP server → external tool

Claude Code as server:
  external MCP client → Claude Code MCP server → Claude Code tool

The protocol does not force every host to implement a different tool engine for each direction. The useful implementation insight is that the tool's description, schema, and execution logic can be reused while the boundary around them changes.

What the reuse does—and does not—prove

This symmetry supports an architectural inference: Claude Code's tool abstraction is not solely a piece of prompt text tied to one conversation loop. It is structured enough to be projected outward as MCP tool metadata and executed when a different program initiates the call.

But there is a limit to that inference. “Same underlying tool implementation” does not mean an external caller inherits exactly the same context, permissions, or user interaction as an interactive Claude Code conversation. The MCP server has its own runtime conditions, tool availability, and security boundary. A client author should inspect what tools/list actually returns and test the calls they intend to make rather than assuming every internal feature is exposed or behaves identically.

The analogy with Part 4 is still useful. There, Claude Code brought external MCP tools into its tool catalog, giving each one a server-qualified name. Here, it takes tool definitions on the inside and presents them through MCP. Both directions depend on describing an operation in a way another component can discover and call.

The permission discussion in Part 5 remains relevant too. Exposing a callable capability is not the same as declaring every call safe. If you let another application launch claude mcp serve, treat that application's configuration and the resulting tool access as a real trust decision. The outside client is no longer merely reading a document; it is gaining a path to actions performed by the Claude Code process.

A practical integration shape

A compatible local MCP client generally needs a server configuration that launches the claude executable with mcp serve as its arguments. The client starts the subprocess, negotiates MCP, requests tools/list, and can then issue tools/call for the exposed names. There is no separate remote HTTP endpoint implied by this command. Standard input and output are the transport; process lifecycle and the local environment are part of the integration.

That makes this feature useful for an IDE or another automation host that already speaks MCP and wants to reuse capabilities Claude Code exposes, rather than reimplementing them from scratch. It is a narrower use case than connecting Claude Code to a familiar Jira or database server, but it completes the picture of MCP as a role-based protocol, not a one-way plugin mechanism.

Earlier drafts of this research treated the reverse role as something visible mainly in source code. The public documentation now explicitly includes “Use Claude Code as an MCP server” and the claude mcp serve command. The implementation detail about converting internal tool schemas remains a source-level observation; the existence of the user-facing command is documented behavior.

The takeaway

Claude Code can be an MCP client, a stdio MCP server, or part of a larger host that mediates several integrations. The roles describe which side discovers and invokes capabilities on a given connection. They do not dictate that a product must have only one role forever.

The final article returns to a practical design question: when a new capability is needed, should it be a Tool, a Skill, an MCP server, or a Plugin?

References

Claude Code MCP Deep Dive (7): From Calling Tools to Reading Resources and Asking Users

Zhengxin — Thu, 29 Oct 2026 02:05:39 +0000

TL;DR: An MCP server can offer more than actions for Claude to call. It can expose resources that a client reads by URI, and it can request information from a person during an operation through elicitation. Claude Code provides common ways to list and read resources across servers, while elicitation can appear as a form or an external browser step. These features make the client–server relationship less one-directional than a simple tool call.

Most of this series has followed one path: Claude chooses a tool, the MCP server runs it, and a result comes back. That is the tools capability introduced in Part 1. This article turns to two other paths: the server makes information available for reading, or it asks the user for information it needs to continue.

Resources: identify and read, rather than invoke an action

Imagine an issue record, a documentation page, or a database schema. A server can expose this material as an MCP resource. The resource has a URI that identifies what should be read; the client asks the server for its contents using the protocol's resources/read operation. This is different from inventing a separate tool and input schema for every kind of document.

In Claude Code, a user can type @ to find resources from connected MCP servers alongside local files. A particular resource can be referenced in a prompt as @server:protocol://resource/path. When referenced, Claude Code fetches it and includes it as an attachment. It also provides general list-and-read tools for MCP resources when connected servers support them.

That is the useful contrast with Part 4. MCP tools are distinct operations whose descriptions and schemas matter individually. Resource discovery and reading are standardized operations; the interesting variation lies in the URIs and the content they return. Claude Code does not need to register a new specialized “read this server's document” tool every time another server is connected.

Resources are often read-oriented context, but “resource” should not be mistaken for a guarantee that every URI is an ordinary text file. MCP resource responses may carry text or binary data, with MIME types indicating what was returned. Claude Code's handling of large or binary output can keep it from dumping an encoded blob directly into the conversation: the implementation examined for this series stores some binary resource content separately and returns a path and description instead. The model can then use the appropriate file workflow if it actually needs to inspect that content.

There is also a boundary worth noting in current Claude Code documentation. Some MCP resources are MCP Apps UI resources, intended for a host application to render. They do not appear in the normal @ resource suggestions or list-tool results, even though reading one by its URI can work. “The server exposes a resource” does not necessarily mean “the resource appears as a document in autocomplete.”

Elicitation: the server asks the user mid-task

Sometimes the server cannot finish an operation with the inputs it has. It may need a missing field, a choice that only the user can make, or a browser-based authorization step. Elicitation is the MCP mechanism for asking the client to obtain that information from a person and return an answer to the server.

This reverses the usual direction of a tool call. Claude or the client initiated an operation, but the server now has a question. The client remains responsible for presenting that question and controlling what information is shared. Elicitation is not a license for a remote server to silently scrape user input.

The capability is negotiated as part of the MCP connection discussed in Part 2. A server can use a mode only when the client has declared that it supports it. In current Claude Code, the user-facing forms are:

Form mode: Claude Code displays fields supplied by the server and returns the submitted answer.
URL mode: Claude Code asks whether to open an external link, so the user can finish a step such as sign-in in the browser.

Claude Code's documentation says no special user configuration is required for these dialogs to appear. It also documents an Elicitation hook that can supply a programmatic response without showing a dialog. That shortcut is a client-side automation choice, not the general definition of elicitation in the MCP protocol. It should be configured with care: an automatic answer may be appropriate for a predictable, low-risk question, but not for a consent decision the user ought to see.

Why protocol version matters here

Elicitation is younger than the basic tools-and-resources model. The June 2025 specification explicitly introduced it as a feature whose design could evolve. Current Claude Code documentation describes form and URL modes, with the capabilities it declares varying by the protocol revision used on a connection.

The MCP specification has also been moving toward stateless operation and more explicit ways to resume work after user input. In that model, a server need not hold an entire request and connection open while a person thinks or switches to a browser; it can return a description of the missing input and enough state to continue later. That direction is useful for scalable server deployments, but it is important not to treat every revision's interaction details as interchangeable. Check the protocol version and client support when implementing or debugging elicitation.

The bigger picture

Tools, resources, and elicitation solve different problems:

Capability	Direction	Main purpose
Tool	Client → server	Invoke an operation with structured arguments.
Resource	Client → server	Retrieve context identified by a URI.
Elicitation	Server → client → user	Obtain missing information while work is underway.

The same MCP connection can make all three useful, but it does not force them into the same UI or permission path. An issue tracker may expose actions for editing issues, resources for reading existing issue data, and elicitation for a decision that cannot safely be inferred.

Next, the series changes perspective. Claude Code is not only an MCP client that connects to other servers; it can also run as an MCP server and offer capabilities to another client.

References

Claude Code MCP Deep Dive (6): From One Authorization to Multiple Servers

Zhengxin — Wed, 28 Oct 2026 02:02:40 +0000

TL;DR: A remote MCP server that needs authentication has not necessarily failed to connect permanently. Claude Code can guide a user through browser-based OAuth, retain credentials securely, and refresh them later. In an enterprise deployment that supports Cross-App Access, one login to the organization's identity provider can also be reused to obtain server-specific access tokens without a separate browser prompt for every server.

Part 5 explored the permission decision after a tool becomes available. But Part 2 left another gate open: what happens when a remote server exists in configuration but cannot yet authenticate the client?

This is a different problem from deciding whether Claude may invoke a tool. OAuth determines whether the MCP client has a credential that the remote service accepts. Claude Code's tool permissions determine whether an individual call should proceed. Passing one gate does not automatically pass the other.

“Needs authentication” is an actionable state

Claude Code distinguishes a remote server that needs sign-in from an ordinary connection failure. Its current documentation says that an HTTP 401 Unauthorized or 403 Forbidden can mark a remote server as needing authentication. The /mcp panel shows which servers need sign-in; an interactive user can authenticate there, or run claude mcp login <name> from a shell.

The distinction matters because an authentication challenge has a clear next step. The server definition does not need to be deleted and recreated merely because credentials are missing. Finish the authorization flow and Claude Code can reconnect with valid credentials.

The code path examined for this series also includes a useful bridge back into the model's tool list. For an eligible server in the needs-auth state, it can expose a synthetic mcp__<server>__authenticate tool instead of leaving the model with no actionable capability. Calling that tool starts the OAuth flow and returns an authorization URL for the user. Once the callback succeeds, the client reconnects and replaces the temporary authentication entry with the server's real tools. This model-facing route complements the documented /mcp and CLI routes; it does not mean the model can sign in on the user's behalf.

There are boundaries to this behavior. The synthetic entry is for the HTTP/SSE OAuth path in the implementation examined here. A claude.ai connector uses its own authorization flow, and a noninteractive run cannot simply pop open an interactive /mcp sign-in dialog. In those cases the user needs the appropriate interactive route first.

The ordinary OAuth round trip

For a remote server that supports OAuth, the sequence is familiar:

Claude Code discovers the authorization information associated with the remote MCP endpoint.
It starts a temporary local callback listener and opens, or provides, the authorization URL.
The user signs in and grants the requested access in a browser.
The authorization server redirects to the callback address with an authorization result.
Claude Code exchanges that result for credentials, stores them securely, and reconnects to the MCP server.

Claude Code's documentation notes that tokens are stored securely and refreshed automatically. That should not be paraphrased as “the token is always in the operating system keychain on every platform”: storage details vary by platform and credential type. The practical point is that the access token is not meant to be pasted into a shared .mcp.json server definition.

The browser step also has a headless-friendly path. If no local browser is available—for example, when claude mcp login <name> runs over SSH—the command prints the authorization URL. The user opens it on a machine with a browser and pastes the full redirect URL back into the interactive terminal. A failed browser redirect can be recovered in the same way. This is why the flow can still work when the terminal and browser are not on the same machine.

Once signed in, the ordinary case is quiet: Claude Code refreshes credentials when needed rather than requiring a browser login for every tool call. If an already-authorized remote server rejects a stored token with 401, current documentation says Claude Code refreshes it, reconnects, and retries the request once. Only if recovery fails does it surface the need to re-authenticate. A configured static Authorization header is different: if the server rejects that header, Claude Code reports a failed connection instead of silently switching to OAuth.

One enterprise identity, several server-specific tokens

A team may operate separate MCP servers for issues, documents, metrics, and internal APIs. Making every employee complete an unrelated browser consent flow for each server is cumbersome. Enterprise-Managed Authorization, also called Cross-App Access (SEP-990), addresses this with a shared enterprise identity provider (IdP).

The high-level sequence is:

One browser login to the enterprise IdP
  → reusable IdP identity token
  → token exchange for the target MCP authorization server
  → server-specific MCP access token

The intermediate exchanges are not a claim that one bearer token should be sent indiscriminately to every server. The client uses the existing enterprise identity to request a credential scoped to the target authorization server. The MCP TypeScript SDK describes the two protocol steps: RFC 8693 token exchange produces an Identity Assertion Authorization Grant (ID-JAG), and RFC 7523's JWT bearer grant exchanges that assertion for an access token at the MCP authorization server.

In the Claude Code implementation examined for this series, the IdP login is cached and reused across servers configured for this flow. The IdP connection is configured once, while each participating MCP server opts in and supplies the details its authorization server needs. With a valid cached identity token, a subsequent server can complete the exchange without another browser interruption. It is not an unconditional “log in once and gain access to every server” promise: the enterprise IdP, each authorization server, the server configuration, and organizational policy must all support and permit the exchange.

This path is explicitly gated. The implementation uses a feature switch and enterprise IdP setup, and a server that opts into Cross-App Access does not silently fall back to ordinary per-server OAuth if the enterprise flow is misconfigured. A visible error is better than an ambiguous security posture where the configuration says one thing and the client does another.

Authentication can expire after a successful connection

A sign-in problem can arise at two points. The first is the initial connection, before the client can list tools. The second is later, after a working server rejects a call because a token expired, was revoked, or lacks the required scope.

The recovery path is not always “show the browser again.” Claude Code first uses its stored refresh credential where possible, reconnects, and retries once. If the refresh token itself is rejected, it points the user back to /mcp for re-authentication. If the server requests an additional OAuth scope, that is a different signal: the client may need a new consent flow with the appropriate scope, and an administrator's pinned scope policy may need review.

Treating these outcomes distinctly prevents two mistakes. A transient 401 need not make a working integration look permanently broken, while a genuinely missing permission must not be hidden behind endless retries. The server's authentication state and the next action should remain legible to the user.

What to remember

An MCP connection can be configured, discoverable, and still unusable until the client is authenticated. Claude Code's OAuth flow turns that state into an actionable sign-in path; secure credential storage and refresh make subsequent use less disruptive. Enterprise Cross-App Access can reduce repeated sign-ins further, but only for servers and organizations explicitly configured to support it.

The next article moves beyond tool calls. MCP servers can also offer resources for reading, and elicitation provides a way to request information from the user while a server-side workflow is in progress.

References

Claude Code MCP Deep Dive (5): From Tool Name Matching to Server-Level Authorization

Zhengxin — Tue, 27 Oct 2026 02:08:47 +0000

TL;DR: An MCP tool’s canonical name carries its server identity. That gives Claude Code a useful permission scope: a single rule can cover every tool from one server. It does not make an external tool intrinsically safe, though. In the usual manual-permission flow, a call without an applicable allow rule asks the user; a server can also mark a sensitive tool as requiring an explicit approval on every call.

The previous article ended at the point where a discovered MCP capability becomes a tool in Claude Code’s tool list. That raises the next question: once Claude can see a renamed MCP tool, may it simply invoke it?

The answer is shaped by the permission system. This article focuses on the MCP-specific part of that system: how a tool name becomes a policy boundary, why that boundary can be a whole server, and why server trust and per-call authorization remain separate decisions.

One rule can cover an entire server

A Claude Code MCP tool is named in the form:

mcp__<server>__<tool>

That name is more than display metadata. It preserves where the capability came from. For example, the tool name mcp__jira__create_issue says both what Claude wants to call and which server provides it. The MCP protocol itself asks a client to discover tools with tools/list; each tool definition has a unique name, a description, and an input schema. Claude Code adds the server-qualified name so that separately connected servers do not collapse into one flat, ambiguous namespace.

That structure gives permission rules a useful extra level of granularity. According to Claude Code’s current permission syntax:

{
  "permissions": {
    "allow": [
      "mcp__jira__*"
    ]
  }
}

The rule matches every tool exposed by the jira server. A rule such as mcp__jira__create_issue instead targets just that one tool. For a configured server with punctuation or spaces, Claude Code uses its normalized server segment in the tool name. A server supplied by a plugin uses a plugin-scoped server name.

This is particularly practical for a server that exposes a family of related operations. A Jira server might provide issue lookup, creation, comments, transitions, and project metadata. A team can decide that this specific integration is acceptable and express the policy once, rather than maintain an ever-growing list of individual tool names as the server evolves.

There is an important constraint: allow-rule wildcards are intentionally narrower than deny and ask wildcards. An allow rule needs the literal mcp__<server>__ prefix, so a broad entry such as mcp__* does not silently auto-approve every MCP tool from every server. The policy must name the particular configured server it trusts.

The name creates a policy boundary

The useful comparison is not “MCP tools versus safe built-in tools.” It is “a capability from a known server versus a capability from somewhere else.” Claude Code’s built-in tools can have tool-specific rules and, for some categories, additional action-specific handling. An MCP tool is an extension supplied by a server: it can query an API, edit a ticket, read a database, or trigger an operation outside the local project.

Its server-qualified name lets the client apply a consistent rule before issuing the tools/call request:

The server advertises a tool through tools/list.
Claude Code gives the exposed capability a full mcp__<server>__<tool> name.
Permission policy checks that canonical name against deny, ask, and allow rules.
Only an allowed call is sent to the server as tools/call.

This is also why a server-wide rule is meaningful. It does not claim that all tools are harmless; it records a deliberate trust decision about the server namespace. An organization may allow all tools from an approved internal service, ask before calls to a staging service, and deny an unapproved server altogether.

The reverse works too. A deny or ask rule can use a full-name pattern such as mcp__* to govern MCP tools across servers. A policy can therefore make the default posture explicit rather than relying on the apparent friendliness of a tool’s description.

No rule should be mistaken for no decision

In Manual mode, Claude Code’s permission system normally presents an approval prompt for actions that require approval. MCP tool prompts are part of that flow, and the permission dialog lets the user approve or deny the proposed call. A matching allow rule can avoid routine prompts for the precise scope it names; a deny rule blocks the call.

That distinction matters when installing a new MCP server. Connecting a server, exposing its tools, and authorizing a particular action are related but different events. A server may be correctly configured and successfully connected while its tools still require approval according to the active policy.

The Model Context Protocol makes the same safety principle explicit: implementations should keep a human able to deny tool invocations, show which tools are exposed, and present confirmations for operations. The protocol defines how a server advertises and receives tool calls; it does not declare that a given remote operation is safe.

Claude Code also supports a stronger signal from the server itself. An MCP server author can set:

{
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

on an individual tools/list entry. Claude Code then requires an explicit approval on every call to that tool, even if a matching allow rule exists or a permissive mode is active. This is appropriate for actions where the human confirmation is itself the point, such as granting access to a protected resource.

Trust is layered, not inherited

The server-level wildcard is a convenience, not an automatic security proof. MCP servers may reach external services and handle data outside Claude Code’s local runtime. Claude Code’s MCP documentation therefore advises users to verify that they trust each server before connecting it, especially when a server can fetch external content and expose prompt-injection risk.

A sound policy separates several questions:

Question	Example decision
Should this server connect?	Approve a known internal Jira server; reject an unknown one.
Should Claude see this capability?	Deny a particular tool or all tools from a server.
Should this call run now?	Ask for approval, or allow a narrowly defined trusted scope.
Must a person always confirm?	Mark a sensitive server tool with `requiresUserInteraction`.

This layered model is more durable than trying to infer safety from a tool name or natural-language description. A permission rule makes the intended boundary visible, reviewable, and shareable through settings. The server still owns the implementation; the client still owns the decision to invoke it.

What to remember

MCP tool names encode provenance, and that provenance becomes a practical authorization boundary. Use a full tool name when one operation deserves its own policy. Use mcp__<server>__* when a team has consciously chosen to trust a particular server’s whole tool family. Avoid broad allow rules that erase the distinction between servers.

Most importantly, do not equate discovery with authorization. Seeing a tool in the list means Claude Code knows how to call it. A permission rule and, when appropriate, a human approval determine whether it should call it now.

The next article follows the other gate that can prevent a server from becoming usable: authentication. We will trace how a server moves from “needs authentication” to an active connection, including the browser-based authorization step and how credentials can be reused across servers.

References

Claude Code MCP Deep Dive (4): From Tools List to an Entry in the Tool List

Zhengxin — Mon, 26 Oct 2026 05:37:49 +0000

TL;DR: An MCP server can say, “I have a tool named create_issue,” but Claude Code does not simply put that bare name beside its built-in tools. It gives the tool a namespaced callable identity and adapts the server’s definition into the client’s tool surface. The namespace prevents collisions; the adapter makes a built-in action and an external action look like one coherent tool system to the model.

The previous article covered how bytes move between Claude Code and an MCP server. This article starts after the connection and initialization succeed: how does a tool declared by the server become something the model can actually call?

First, give every external tool a stable namespace

Imagine two connected servers, jira and linear. Both happen to offer a tool called create_issue.

If a client placed two bare create_issue entries in a shared tool list, the model would have no reliable way to select one. The collision can be even more confusing when a server declares a name that resembles a built-in tool. A call named Write should not ambiguously mean either “write a local file” or “invoke an unrelated external service.”

Claude Code resolves this by constructing a callable name that records the tool's origin. For a normally configured server, the shape is:

mcp__<server-name>__<tool-name>

So the two issue-creation tools become distinct entries such as:

mcp__jira__create_issue
mcp__linear__create_issue

The exact shape can gain more scope when a plugin bundles the server. Claude Code's current documentation, for example, gives plugin-provided tools the form:

mcp__plugin_<plugin-name>_<server-name>__<tool-name>

That additional context is not cosmetic. It lets names remain unique even when plugins, manually configured servers, and built-in capabilities share a session.

A useful consequence is that a tool name is also provenance information. The mcp__ prefix signals an MCP-provided capability, and the following namespace identifies the server that owns it. In the next article, that naming pattern will matter again because permission rules can target a server's tools as a group rather than requiring one rule per tool.

The server supplies the tool contract

Built-in tools are implemented and described by Claude Code itself. An MCP tool arrives differently: the server declares it through the protocol.

The MCP tools/list response includes a tool name, a human-readable description, and an inputSchema expressed as JSON Schema. It may also include a title, an output schema, and annotations. Claude Code can use that declaration to present a call surface to the model without inventing a second, client-owned parameter format for every server.

This is an important division of responsibility:

The server owns the meaning of its tool and the shape of its arguments.
The client owns connection, namespacing, tool availability, presentation, and safety controls.
The model receives a usable tool definition and decides whether that capability fits the user's request.

Suppose a server declares this simplified tool:

{
  "name": "create_issue",
  "description": "Create an issue in the selected project",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "body": { "type": "string" }
    },
    "required": ["title"]
  }
}

The client does not need to translate title and body into a separate proprietary language before the model can use them. It preserves the server's contract while wrapping the invocation route: when the model calls the namespaced tool, Claude Code can map it back to the owning server and issue the corresponding tools/call request.

That is why adding an MCP server can add useful capabilities without requiring Claude Code to ship a new built-in implementation for each service. The server provides the domain-specific schema and behavior; the client provides the integration framework.

One tool surface, regardless of origin

After adaptation, an MCP tool participates in the same broad decision loop as a built-in tool: it has a callable name, a description, an input contract, and a result.

The model should not need a separate decision procedure just because one action came from a remote issue tracker and another came from the local environment. It evaluates the available capabilities against the request, chooses an action, supplies arguments, and receives a result.

That does not mean origin disappears. It remains important for permissions, connection health, timeouts, and diagnostics. But it is intentionally not a burden on the model-facing interface. The client hides the transport and server-routing machinery behind a consistent tool abstraction.

For server authors, this has a practical implication: invest in a precise description and a clear JSON Schema. A vague description or underspecified schema does not become clearer when it crosses the MCP boundary. The client's wrapper can make the tool available; only the server can explain what a valid invocation means.

A namespace is safer than a replacement

The normal behavior is namespacing, not replacement. A distinct mcp__... callable name means an external tool cannot silently shadow a built-in tool with the same short name.

Some embedding environments can make more specialized choices about their tool surface, including in-process SDK-hosted servers. Those are host-level design decisions, not a reason for a normally configured third-party server to depend on unprefixed overrides. Claude Code's public MCP configuration documentation explicitly distinguishes an SDK-only in-process server type from the regular configuration types.

The boundary is worth keeping clear: if a system intentionally replaces or aliases a capability, it still needs reliable internal provenance for routing and permissions. A display or callable name alone cannot be the whole security model.

Resources should not multiply into duplicate tools

MCP has more than tools. Servers may also offer resources: readable pieces of context or data.

It would be wasteful for every resource-capable server to register its own separate “list resources” and “read resource” tools with identical client-side behavior. A client can instead expose generic resource operations and route a selected resource back to the server that owns it. The user-facing result is a single resource capability model rather than a list that grows with duplicated plumbing every time another server connects.

The same principle appears throughout a good integration layer: server-specific content belongs to the server; cross-server mechanics belong to the client. A later article will examine resources and elicitation in more detail.

A tool list can change after connection

A connection does not freeze a server's capabilities forever. An MCP server that declares the tools capability can say that its list may change by advertising listChanged. When the list changes, the server can send a notifications/tools/list_changed notification.

Claude Code handles this as a refresh problem rather than requiring the user to disconnect and reconnect the server. Its current documentation says that an interactive session fetches the updated list; claude -p and Agent SDK sessions refresh the tool list on the notification. If refresh fails, Claude Code keeps the previously discovered tools, prompts, and resources until a later refresh succeeds.

This explains an otherwise surprising observation: an MCP server can gain or lose a tool during one session without a manual reconnection. The list was not permanently copied at handshake time; it is a cached view that the protocol allows the server to invalidate.

Many servers, one coherent result

With several MCP servers installed, connections can complete at different times. One local process may start quickly while a remote service takes longer; another server may still be authenticating.

The important conceptual result is not the order of those events. Claude Code maintains a unified tool surface with stable naming and routes each namespaced call to the server that provided it. The model sees a coherent set of capabilities rather than needing to reason about a separate ad hoc interface for every connection.

This same design can scale further with tool search and deferred loading, but the basic transformation remains the same:

A server advertises a tool through tools/list.
Claude Code associates it with the server that advertised it.
Claude Code gives it a collision-safe callable identity and exposes its schema.
A later call is routed back to that server as tools/call.

Next: naming becomes a permission boundary

A namespaced MCP tool appearing in the list does not mean every call is automatically approved. One of the questions from the opening article was: who gets to authorize the action?

The naming rule introduced here makes it possible to describe permissions at a useful granularity, including rules that cover an entire server. The next article continues from that boundary: from matching a tool name to server-level authorization.

References

Claude Code MCP Deep Dive (3): From a Child Process to a Remote Service

Zhengxin — Sat, 24 Oct 2026 04:20:59 +0000

TL;DR: The MCP specification defines two standard transports: a locally launched subprocess over stdio, and a remote endpoint using Streamable HTTP. Claude Code also documents compatibility paths such as legacy SSE and WebSocket. Those client-specific options should not be mistaken for the protocol's portable baseline. The transport moves bytes; it does not decide which tools, resources, or prompts the server exposes.

The previous article ended just before the handshake: Claude Code knows a server exists, but it still needs a way to speak to it.

MCP calls that way of speaking a transport. A transport determines how messages travel between client and server. It is separate from the question of what those messages describe—tools, resources, prompts, and the other capabilities a server may advertise. The next article will examine how a declared server tool enters Claude Code's tool list.

The protocol standardizes two transports

The Model Context Protocol standard defines two standard client-server transports:

stdio
Streamable HTTP

Both carry the same JSON-RPC messages. That separation is deliberate: once the protocol layer abstracts the communication mechanism, the application-level interaction should look the same regardless of the transport.

`stdio`: launch a local subprocess

With stdio, the client starts the MCP server as a child process. The server reads JSON-RPC messages from standard input and writes JSON-RPC messages to standard output. Its standard error stream remains available for logging, but standard output must contain valid MCP messages only.

This is the natural shape for a local integration. If an issue-tracker helper is an executable installed on your machine, Claude Code can launch it directly rather than putting a network hop in the middle. Claude Code's MCP documentation describes local stdio servers as a fit for custom scripts and tools that need direct access to the system.

A stdio transport is not “MCP over a terminal” in the casual sense. The process boundary matters. Claude Code owns the child process lifecycle, while the server owns the logic behind the protocol. If the server exits, the connection is gone because the program that supplied it is gone.

Streamable HTTP: connect to a remote endpoint

Streamable HTTP is the standard remote option. The client sends JSON-RPC messages with HTTP requests, and the server may return either a normal JSON response or an SSE stream. A server can also use an HTTP GET request to open an SSE stream for server-to-client messages.

This replaced the older HTTP-plus-SSE transport from the 2024-11-05 protocol revision. The current specification keeps a backwards-compatibility path, but new servers should implement Streamable HTTP rather than build on the retired design.

For a remote server, this distinction matters operationally as well as architecturally. An HTTP endpoint may be separately deployed, authenticated, monitored, and shared by many clients. The transport boundary is now a network boundary.

The same message shape travels through either path

A transport is a delivery mechanism, not a capability model.

Whether the server is a subprocess or an HTTPS endpoint, the client and server exchange JSON-RPC protocol messages. The server implementation should not need one set of tool semantics for local use and a different set for remote use. It can expose a tools/list response, accept tools/call, and participate in initialization with the same MCP-level meaning on either transport.

That is the practical payoff of the abstraction:

the connection layer chooses how messages get there;
the protocol layer gives those messages a common shape; and
later layers decide how discovered capabilities become available to the agent.

For the code that discovers a tool or calls it, “local process” and “remote service” should not produce two unrelated APIs. They are two implementations of the same connection contract.

Claude Code supports more than the portable baseline

The protocol's two standard transports are the portable baseline. A particular MCP client can additionally support compatibility or product-specific connection paths, and Claude Code does.

Its current public documentation describes four externally configurable server types:

local stdio servers;
remote HTTP servers, with streamable-http accepted as an alias in JSON configuration;
legacy remote SSE servers; and
remote WebSocket servers.

The latter two are useful examples of the difference between a specification and a client implementation. SSE remains available because some services still expose an older endpoint, but Claude Code marks it deprecated and recommends HTTP when possible. WebSocket is a persistent bidirectional connection that is useful for servers that push events without waiting for a request; Claude Code's own docs recommend HTTP when a server only needs request-response behavior.

MCP itself also permits pluggable custom transports. That permission does not make every client-specific transport universally available. When you build a third-party server intended to interoperate broadly, stdio and Streamable HTTP are the dependable choices because they are the two mechanisms the specification standardizes.

The distinction is easy to blur when reading a client codebase. A client may contain adapters for legacy protocols, SDK-hosted integrations, browser or IDE components, or internal wiring that reuse MCP's message handling. Reuse of the message format and lifecycle code does not turn each internal pathway into a general-purpose transport that an outside server author should choose.

An in-process integration can remove the channel entirely

The most extreme client-specific case is an in-process integration: no child process and no network request. Both sides are already in the same process, so they can exchange messages directly while presenting a common MCP-shaped interface to code above them.

Why preserve the abstraction when there is no real transport to manage? Because the rest of the client benefits from a uniform contract. The capability-discovery layer does not need separate logic for “a remote server,” “a local executable,” and “a built-in integration.” It can ask for tools, resources, and prompts through one conceptual interface.

This illustrates what the transport layer is buying: upper layers should not need to care how the bytes moved—or, in an in-process case, whether bytes crossed a boundary at all. The next stage can focus on naming, discovery, permissions, and invocation instead.

Local and remote failures have different recovery paths

A transport choice also changes what a disconnection means.

For a local stdio server, an exit or failed startup points to a process-level problem: a missing executable, invalid arguments, a bad environment, or a crash. Claude Code's current guidance does not automatically retry a failed first stdio connection. In an interactive session, the server is marked failed and can be reconnected from /mcp; in a non-interactive run, a later run or tool call provides the next opportunity to start it again.

A remote connection has a different failure model. A server may be healthy while a network request times out, a proxy returns a transient error, or a connection drops mid-session. Claude Code therefore retries transient remote failures. For a dropped remote server, it first makes up to five reconnection attempts with exponential backoff beginning at one second. For an initial HTTP or SSE connection that fails transiently, it retries up to three times.

These rules are not a claim that local failures are never transient or that network failures always are. They encode a useful operational default:

a local process failure often needs configuration or environment diagnosis;
a remote interruption is more likely to benefit from a bounded retry; and
authentication and not-found errors should normally be fixed rather than blindly retried.

There are details by runtime and server type. In particular, the documented initial-connection retries apply to HTTP and SSE, not stdio or WebSocket. Treat the transport as part of the diagnosis, not just a field in configuration.

The boundary to carry forward

The useful mental model is simple:

The MCP specification provides the interoperable baseline: stdio and Streamable HTTP.
Claude Code can support additional compatibility and product-specific paths, including legacy SSE and WebSocket in its public configuration.
Higher layers should work with the capabilities discovered through the connection, rather than hard-coding assumptions about the channel underneath.

Once the server is connected, initialized, and queried, it may declare a tool such as create_issue. How does that server-side name become an entry the model can call? How are collisions avoided, and how does the tool reach the model's tool list?

That is the subject of the next article: from tools/list to one entry in the Tool list.

References

Claude Code MCP Deep Dive (2): From a Configuration Entry to a Handshake

Zhengxin — Fri, 23 Oct 2026 02:04:16 +0000

TL;DR: Claude Code cannot connect to an MCP server until that server appears in configuration. A definition may be private to one project, shared with a team, available to one user everywhere, or managed by an organization. When the same server name appears in more than one scope, precedence determines which complete definition wins. After configuration comes a separate job: connecting, handshaking, and negotiating the capabilities that server actually supports.

In the previous article, we used an internal Jira server as the motivating example. Where should that server be declared so Claude Code knows it exists?

There is no single answer. It depends on who should use the server and which parts of its configuration are safe to share.

One server name, several kinds of ownership

Suppose a company provides an MCP server for its internal Jira instance. Everyone on a team should be able to use it, but nobody’s API token should be copied into a shared repository.

That is the first configuration problem MCP needs to solve: the connection details for a shared capability should be declared once, while each person can retain control of their private credentials.

Claude Code’s current public documentation describes three regular installation scopes, plus organization-managed configuration:

Project scope lives in a .mcp.json file at the project root. It can be committed to version control, so a team can share the server name, endpoint, and launch method without committing personal credentials.
User scope lives in the user’s ~/.claude.json and applies across that user’s projects. It fits personal utility servers that are unrelated to one repository.
Local scope is also stored in ~/.claude.json, but keyed to one project only. It stays private and does not appear when the user opens other projects.
Managed configuration lets an administrator provide servers centrally for an organization. Individual users do not edit that managed source themselves.

The Claude Code MCP reference documents the storage locations and intended use of these scopes.

The local scope is particularly useful in the shared-Jira scenario. The project’s .mcp.json can declare “this repository uses the Jira server,” while each developer supplies their own credential-bearing configuration privately. The shared repository establishes the integration; the local configuration completes it for one person.

There are also server sources outside this regular scope hierarchy. A session can receive temporary configuration through a command-line option, and connectors configured through Claude.ai can reach Claude Code. Those are separate paths, not substitutes for the ordinary project/user/local choice.

A collision is resolved by precedence, not by field-by-field merging

What if the same server name appears in project, user, and local configuration?

Claude Code resolves that conflict predictably. The public precedence order is:

Local scope
Project scope
User scope
Plugin-provided servers
Claude.ai connectors

Organization-managed server definitions take precedence over all of those when they duplicate a server.

The important detail is easy to miss: Claude Code uses the entire server entry from the winning source. It does not merge individual fields from several scopes into one composite record. That distinction makes debugging less mysterious. If a local definition has the same server name as a project definition, the local definition is the one that Claude Code will use; it is not merely a place to append one extra header to the project record.

This precedence is practical rather than arbitrary. A team can establish a shared baseline in .mcp.json, while an individual retains an explicit way to substitute a private or project-specific definition. If a managed definition exists for the same server, the organization’s definition wins instead.

One more safeguard applies specifically to project-scoped servers. A .mcp.json file usually travels with a repository, so Claude Code asks for approval in interactive sessions before using its project-scoped servers. That makes the connection command and arguments visible before a cloned repository gets to run them. User and local scopes are already the user’s own private configuration, so they do not need the same first-use approval step.

Configuration says “try this,” not “it is usable”

A configuration record is only a declaration that a server should exist. The actual connection still has to be established.

Claude Code tracks a server’s connection state rather than reducing everything to a single yes-or-no flag. States distinguish a connected server from one that failed to connect, is still connecting, is disabled, or needs authentication.

That separation matters because “unreachable” and “reachable but unauthorized” lead to different remedies. A bad URL, missing process, or crashed child process is a connection problem. An expired OAuth session or missing permission is an authentication problem. Treating both as the same generic failure would hide the next useful action.

The connection phase and a later tool call also deserve different timeout expectations. A connection that never responds within a short window is often misconfigured or not running at all. A tool call, by contrast, may ask the server to perform a long-running operation. A client should avoid treating those two waits as if they had the same failure meaning.

The handshake asks what is actually available

A successful transport connection is not yet the end of the setup path. Claude Code still needs to learn what the server supports.

This is capability negotiation. Client and server declare their supported features, and the client enables only the capabilities the server actually advertises. A server might offer tools but no resources; another might expose readable resources while offering no callable tools at all.

That is why MCP should not be described simply as “a way to add tools.” Tools, resources, and prompts are distinct capability families. The Model Context Protocol introduction frames MCP as a standard connection between AI applications and external systems, including data sources, tools, and workflows.

Negotiation keeps that flexibility from becoming guesswork:

If a server does not advertise tools, Claude Code does not ask it for a tool list.
If it does not support resources, resource-reading behavior stays unavailable for that server.
If a feature is supported by both sides, Claude Code can enable the relevant downstream behavior.

The result is an intentionally modest rule: use what the server says it supports, rather than assuming every server implements every part of the protocol.

Connected is not the same as useful

After the handshake and capability negotiation complete, the server is connected. But that still does not mean the model can use a new action yet.

The connection only establishes a working channel and an agreed feature set. The next questions are how bytes move across that channel, and how a declared server tool becomes a normal entry in Claude Code’s own tool list.

Those are separate transformations, and separating them is what makes the system manageable:

Configuration chooses a candidate server.
Connection and handshake establish a usable relationship.
Capability negotiation limits what the relationship can do.
Later layers expose the allowed capabilities to the agent.

The series map provides the broader pipeline, while Part 1 explains why MCP exists at all.

Next: local processes and remote services

A handshake assumes Claude Code already knows how to speak to the server. That may mean launching a local child process and communicating over standard input/output, or making requests to a remote service over a network transport.

The next article examines that transport choice: which connection paths the protocol standardizes, which paths Claude Code supports in practice, and why a local process and a remote service should not be retried or diagnosed in exactly the same way.

References

Claude Code MCP Deep Dive (1): From Built-In Tools to Extensible Capabilities

Zhengxin — Thu, 22 Oct 2026 02:06:46 +0000

TL;DR: Claude Code ships with a fixed set of built-in tools such as Read, Write, and Bash. MCP—the Model Context Protocol—lets it connect to an external process at runtime and use that process’s declared capabilities as new tools. MCP does not solve “how should I reuse a procedure?” That is the job of a Skill. MCP solves “how can the model perform an action it did not ship with?”

Imagine that, before changing code, you want Claude to check the current state of an issue in your company’s internal Jira instance.

Claude Code does not come with a tool named Jira. It could use Bash to assemble a curl command, add an API token, organization domain, and issue ID, build a JSON request, then sift the useful fields from a large response. That can work. But every time, the agent has to reconstruct where the token lives, what the endpoint looks like, and how to interpret the returned fields.

That is a familiar kind of friction. An earlier Skill-focused discussion described it as repeatedly pasting a release checklist. Here, the repeated context is not a checklist but the mechanics of talking to an external system.

A natural reaction is: why not turn those curl steps into a Skill?

You can—but the Skill would package operational knowledge about how to talk to Jira. The actions available to Claude would still end at Bash. A Skill can organize the use of existing tools; it does not add a new executor. If the Jira integration needs to maintain session state, deal with pagination, or interpret schemas that differ by permission level, repeatedly composing requests and parsing them in Bash is less dependable than calling a purpose-built action that already understands Jira.

What is missing is not another set of instructions. It is a new action: something with a name, parameters, and a result, which the model can invoke directly like Read or Bash. Built-in tools are part of Claude Code itself. You cannot edit the product’s code just to make it recognize Jira.

That is the layer MCP addresses: how can a model gain a new action at runtime without changing Claude Code itself?

A connectable process, not a text file to read

A Skill is a folder containing Markdown and supporting files. Claude reads and expands it. An MCP server is different: it is an independently running process or service.

It might be a local program that can access a filesystem, or a long-running server inside a company network. It declares that it offers particular tools, readable data, and reusable prompt templates. The protocol gives that declaration a common shape regardless of the language used to build the server or the machine on which it runs.

This series will call that process an MCP server.

On the other side, Claude Code acts as an MCP client. It connects to a server, asks what that server can do, and adapts the answer into a form Claude Code can use. From the user’s perspective, the larger application is the host: it can manage several MCP clients and several servers at once.

Those names—host, client, and server—are general Model Context Protocol terminology, not concepts invented solely for Claude Code. The same vocabulary applies when an IDE or another desktop assistant supports MCP. The MCP introduction describes the protocol as an open standard for connecting AI applications with external systems.

An MCP server can declare more than one kind of capability. Three categories matter for this series:

Tools are callable actions that may have side effects, such as creating a Jira issue. They are the real answer to the opening scenario and the main thread of the series.
Resources are readable data exposed by a server, such as a current issue list. They are not the same as the supporting resources inside a Skill folder: these are externally supplied, potentially live data.
Prompts are reusable conversation templates provided by a server. They are useful, though less central here than tools and resources.

Connecting one server does not imply that all three categories exist. A server may expose only tools, only resources, or some combination. The client first needs to learn what the server supports. For a practical overview of the kinds of external systems Claude Code can connect to, see the official Claude Code MCP documentation.

The important point for now is simple: tools, resources, and prompts are three different things.

Once connected, it looks like an ordinary tool

Suppose an MCP server declares a create_issue tool. Claude does not see it as a special “external capability.” Claude Code names and wraps it so it becomes another entry in the normal tool list, alongside Read and Bash.

That uniformity is the design decision that makes MCP useful. The model need not switch into a separate “MCP mode” before deciding whether to call a tool. The source may be external, but the agent-facing shape remains a tool name, description, input schema, and result.

The previous article in this series maps the full route from server configuration to a callable tool. The rest of the series will unpack the main questions along that route:

Where does a server come from? A server can be configured at several scopes. How does Claude Code discover the configuration and resolve conflicts?
How do bytes move? A local child process and a server inside a private network cannot use exactly the same connection path.
How does naming work? Why does a connected tool such as create_issue not collide with a built-in tool, and how does it reach the list the model can see?
Who approves an action? If a server can reach an internal network or create issues, who authorizes it? Can approval apply to the whole server rather than require a separate decision for every tool?
Where is the boundary with Skills? Both extend what Claude can accomplish, but they do so at different layers.

Draw the line with Skills early

The detour through “should this be a Skill?” is not a distraction. It is worth establishing the boundary at the start because every later article relies on it.

	What it solves	Where it ends
Skill	Reusable operating knowledge: what to do first, and what to do after each result	It invokes existing tools
MCP	An action the model did not ship with	It adds a new tool

The two mechanisms are complementary. Once an MCP server adds a useful tool, a Skill can absolutely include that tool in a repeatable workflow. One layer defines how to proceed; the other changes what actions are available at all.

A compact way to remember the distinction is:

Skills answer “how do I do this?” MCP answers “what can I do?”

That framing also clarifies why MCP should not be treated as a bag of prompt snippets or shell recipes. It is a protocol boundary that lets independently built capabilities enter an agent without turning the agent itself into a collection of special cases.

Next: configuration becomes a connection

Before Claude Code can connect to an MCP server, that server must appear in configuration. The same name might be defined in a project, a user-level configuration, or centrally managed settings. What happens when those sources disagree?

The next article follows that path: from the first configuration entry, through scope and precedence, to a completed handshake and a client that knows which capabilities the server supports.

References

Claude Code MCP Deep Dive (0): The Connection Lifecycle and Tool Exposure Map

Zhengxin — Wed, 21 Oct 2026 04:53:15 +0000

MCP gives Claude Code a second source of capabilities. Built-in tools are not the whole story: once a server is connected, its tools, resources, and prompts become available to the client. The interesting part is that Claude Code does not build a separate agent runtime for those tools. It translates an external tool into the same general tool surface used by the agent loop.

That design choice is the thread for this series:

The more extensible the system becomes, the more important a single, uniform interface becomes.

This opening article is a map of the territory. Later articles will follow each section of the pipeline in detail.

The path from configuration to a callable tool

A server entry in .mcp.json or user settings does not immediately become something the model can call. It crosses several gates:

Merge configuration scopes. Claude Code combines the relevant configuration sources and resolves overrides.
Apply policy. Allowlists, denylists, and enterprise rules may remove a server before connection is attempted.
Obtain approval. A project-level server can require the user's approval before first use.
Connect through the selected transport. A local child process and a remote HTTP service have different connection paths.
Negotiate capabilities. Client and server establish which MCP features are supported.
Discover capabilities. The client fetches the server's tools, resources, and prompts.
Adapt tools. Each server tool becomes an MCPTool with a Claude Code-compatible name and schema.
Add it to the agent's tool list. At that point, the LLM can select it as if it were an ordinary tool.

Each stage can fail differently. A failed connection becomes a connection failure. An expired authorization becomes an authentication problem. A policy rejection is quieter: the server can disappear before the user ever sees a connection state.

That distinction matters when debugging MCP. “The tool is missing” can mean a configuration merge issue, a policy decision, an approval requirement, an authentication failure, or a transport failure—not merely that tools/list failed.

For the user-facing setup model and supported scopes, see the official Claude Code MCP documentation.

Connection is a lifecycle, not a one-time request

Internally, a server is not simply connected or disconnected. The connection layer distinguishes states such as connected, failed, pending, disabled, and needing authentication. That state model prevents a transient transport error from being confused with an OAuth flow that still needs a browser-based decision.

The implementation also treats a connection as a cacheable resource. A connection is memoized by server name and configuration, then its derived data—such as discovered tools and resources—is cached alongside it. When the transport closes, those caches are cleared so the next request takes the reconnection path instead of continuing to use stale discovery results.

This is especially important for remote MCP servers. A session can expire even when the endpoint remains reachable. Claude Code recognizes the relevant JSON-RPC session-expiry failure, clears its cached connection state, reconnects, and retries once. It is a small recovery rule with a large practical effect: “the server is up” is not the same as “this session is valid.”

There is also an intentional split in retry behavior. Remote transports can receive bounded automatic reconnect attempts with exponential backoff. Local stdio and SDK-backed processes are excluded. A network connection may recover after a short interruption; a local process that exited is more likely to have a bad command, missing environment variable, or a real crash. Retrying blindly would obscure that diagnosis.

Standard transports and product transports

The MCP specification defines the standard stdio and Streamable HTTP transports; the older HTTP-plus-SSE approach is deprecated. The protocol's transport specification is deliberately narrow: it standardizes interoperable ways to exchange JSON-RPC messages rather than every integration a product might need. See MCP's transport specification.

Claude Code's client has a broader set of branches in practice. In addition to standard local and remote paths, the codebase contains support for compatibility SSE paths, WebSocket-based paths, IDE-oriented variants, SDK bridges, a Claude.ai proxy, and an in-process transport.

This is not a contradiction. It is the boundary between a protocol and a product:

The protocol defines the portable contract that independent clients and servers can share.
The product still needs integrations for its IDE, browser, SDK, and internal process boundaries.

The in-process transport makes this visible. It passes messages through in-memory queues rather than a network connection or child process. The SDK bridge similarly carries MCP JSON-RPC messages across Claude Code's own control channel. Neither changes the model-facing idea of a tool; both solve deployment-specific plumbing.

How an external tool becomes a Claude Code tool

The key adapter is naming. A discovered MCP tool is exposed as:

mcp__<server>__<tool>

That prefix gives tools from different servers a stable namespace and lets the rest of Claude Code treat them like entries in a common list. The tool's inputSchema is passed through as JSON Schema rather than translated into a separate handwritten validation model.

The result is deliberately mundane: a model sees a tool name, a description, and a schema. It does not need a separate mental model for “MCP mode.”

The adapter also exposes one limitation of every string-based namespace: server names containing the separator can be ambiguous. Names are convenient as human-facing identifiers, but they are a brittle serialization format when later parsing needs to recover structural boundaries.

Claude Code also registers resource-listing and resource-reading functionality globally rather than once per server. That avoids presenting the model with a growing cluster of nearly identical resource tools as more servers are connected. Large or binary resource results can be stored as files and replaced with a path reference, and MCP output has a configurable size limit. Both measures keep a capable external server from consuming the entire working context.

MCP permissions: special matching, ordinary decisions

MCP has one notable extension in Claude Code's permission grammar. A rule can match an entire server, for example:

mcp__calendar
mcp__calendar__*

That is more useful than approving every tool individually when a server offers a coherent, trusted capability. It also allows a user or administrator to deny an entire integration at the same level of abstraction at which it was installed.

But the MCP tool itself does not carry a private permission engine. Its local permission check returns passthrough; the shared permission system performs the actual rule matching. If no rule resolves the request, the general engine falls back to asking the user.

This is a useful division of responsibility. A tool such as Bash may need command-specific safety analysis. An MCP tool is too varied for one universal semantic rule. Claude Code instead centralizes the decision in the policy layer, where the server namespace provides the necessary grouping mechanism.

Beyond tools: resources, prompts, and elicitation

MCP is often described as “a way to add tools,” but that is only one of its three major capability families:

Tools let the model perform an action.
Resources let a server provide readable, addressable information.
Prompts let a server provide reusable prompt templates.

Claude Code gates each downstream feature independently after capability negotiation. A server may be useful as a tool provider without offering resources, or vice versa.

Elicitation is the more interactive extension. It lets a server request structured input while an interaction is in progress. Claude Code supports form and URL modes, and places hooks in front of the UI so an installation can handle certain requests programmatically. This is a good example of the difference between adopting an MCP feature and shipping it in a real product: protocol support establishes the message exchange; a client still decides how a person sees, approves, or automates that exchange.

Authentication is part of the tool experience

For HTTP servers, authorization is not a detached setup screen. An authorization failure can surface to the model as a synthetic authentication tool result containing the URL needed to continue the flow. Under the hood, the client uses authorization-code OAuth with PKCE, a local loopback callback, a timeout, and secure credential storage.

This makes authentication another state transition in the lifecycle rather than an unstructured fatal error. Enterprise environments add another layer: a token-exchange flow can reuse an existing identity-provider session across eligible servers, reducing repeated logins without changing the core tool interface.

Claude Code can reverse roles

The architecture becomes clearer when the direction is reversed. Claude Code can also start an MCP server and expose its own internal tools through tools/list, using stdio for another MCP client to consume.

That works because tool definitions are not fundamentally tied to one transport. The same internal schema can be used directly by the agent loop or converted to JSON Schema and advertised over MCP. Claude Code is therefore not permanently “an MCP client”; MCP is one of the ways its tool model can cross a process boundary.

What the rest of the series will explain

This map suggests the chapters ahead:

Connection setup, scopes, and the handshake.
Local and remote transports.
Tool discovery, naming, schemas, and output control.
Server-level permission rules.
OAuth and enterprise authentication.
Resources and elicitation.
Claude Code acting as an MCP server.
Where MCP stops—and where Skills, built-in Tools, and Plugins begin.

The central question is not “How do I add another tool?” It is: how can an agent accept many independently built capabilities without becoming a pile of special cases? Claude Code's answer is to make the boundary adaptable, then keep the agent-facing interface uniform.

DEV Community: Zhengxin

Claude Code Skills Deep Dive (1): From a Markdown File to a Portable Folder

One Markdown file soon becomes three kinds of material

SKILL.md is an entry point, not a warehouse

What the open format standardizes

What Claude Code adds

The apparently contradictory name field

A script does not turn a Skill into a tool

An asset is not a reference

Why custom commands converged with Skills

References

Claude Code Skills Deep Dive (0): From Repeated Prompts to Callable Capabilities

Save the workflow as a folder

Selection resembles tool selection—but execution does not

The folder can carry more than instructions

What happens after installation?

Three layers, three costs

References

Claude Code MCP Deep Dive (9): Where MCP Ends and Skills, Tools, and Plugins Begin

Start with the boundary, not the acronym

A bundled script, a local tool, or an MCP server?

One new server, or one more tool on an existing server?

Many servers: should they become a plugin?

Closing the series

References

Claude Code MCP Deep Dive (8): From MCP Client to MCP Server

One tool definition, another exit

What the reuse does—and does not—prove

A practical integration shape

The takeaway

References

Claude Code MCP Deep Dive (7): From Calling Tools to Reading Resources and Asking Users

Resources: identify and read, rather than invoke an action

Elicitation: the server asks the user mid-task

Why protocol version matters here

The bigger picture

References

Claude Code MCP Deep Dive (6): From One Authorization to Multiple Servers

“Needs authentication” is an actionable state

The ordinary OAuth round trip

One enterprise identity, several server-specific tokens

Authentication can expire after a successful connection

What to remember

References

Claude Code MCP Deep Dive (5): From Tool Name Matching to Server-Level Authorization

One rule can cover an entire server

The name creates a policy boundary

No rule should be mistaken for no decision

Trust is layered, not inherited

What to remember

References

Claude Code MCP Deep Dive (4): From Tools List to an Entry in the Tool List

First, give every external tool a stable namespace

The server supplies the tool contract

One tool surface, regardless of origin

A namespace is safer than a replacement

Resources should not multiply into duplicate tools

A tool list can change after connection

Many servers, one coherent result

Next: naming becomes a permission boundary

References

Claude Code MCP Deep Dive (3): From a Child Process to a Remote Service

The protocol standardizes two transports

stdio: launch a local subprocess

Streamable HTTP: connect to a remote endpoint

The same message shape travels through either path

Claude Code supports more than the portable baseline

An in-process integration can remove the channel entirely

Local and remote failures have different recovery paths

The boundary to carry forward

References

Claude Code MCP Deep Dive (2): From a Configuration Entry to a Handshake

One server name, several kinds of ownership

A collision is resolved by precedence, not by field-by-field merging

Configuration says “try this,” not “it is usable”

The handshake asks what is actually available

Connected is not the same as useful

Next: local processes and remote services

References

Claude Code MCP Deep Dive (1): From Built-In Tools to Extensible Capabilities

`SKILL.md` is an entry point, not a warehouse

The apparently contradictory `name` field

`stdio`: launch a local subprocess