Setting Up MCP Servers in Subagents: Inline Configurations vs. Server Name References

Claude Code subagents support two methods for attaching MCP servers: referencing a server name defined in .mcp.json for shared configurations, or embedding the complete server definition inline within the subagent's front matter for self-contained deployments.

Claude Code extends subagent capabilities through the Model Context Protocol (MCP), allowing specialized tools and context to be attached to individual agents. This guide explores the two configuration patterns available in the mcpServers front-matter field, as documented in the shanraisshan/claude-code-best-practice repository, helping you decide between centralized server references and inline definitions.

Understanding the mcpServers Front-Matter Field

According to best-practice/claude-subagents.md, the mcpServers field accepts an array where each entry may be either a string (server name reference) or an object (inline configuration). This flexibility allows teams to choose between shared, project-wide server definitions and agent-specific configurations.

When Claude Code initializes a subagent, it parses the mcpServers array in the agent's front matter. String values trigger a lookup in the merged MCP configuration hierarchy, while object values are treated as complete, standalone server definitions that bypass external configuration files.

Server Name References vs. Inline Configurations

Server Name References (String Values)

A server name reference uses a simple string like "playwright" or "context7" that corresponds to a key defined in the project's .mcp.json or the user's ~/.claude.json. This approach promotes reusability by allowing multiple subagents to share a single server definition.

The resolution follows a strict hierarchy documented in best-practice/claude-mcp.md: Subagent > Project > User. If the same server name exists at multiple levels, the subagent-specific configuration takes precedence, followed by project-wide settings, then user-wide defaults.

Inline Configurations (Object Values)

An inline configuration embeds the complete server definition directly within the subagent's front matter as a YAML object. This method includes the command, args, and any other necessary parameters required to launch the MCP server.

When Claude encounters an object in the mcpServers array, it treats the entry as a complete server definition and does not consult .mcp.json. This creates a self-contained agent that documents its own dependencies within its definition file.

Configuration Resolution Hierarchy

The resolution process works in three distinct steps as implemented in Claude Code:

1. Front-matter parsing: Claude examines the mcpServers array in the subagent file (located in .claude/agents/*.md).

2. Type detection: If an entry is a string, Claude searches for that key in the merged configuration hierarchy starting at the subagent level, then project .mcp.json, then user ~/.claude.json (lines 15-22 of best-practice/claude-mcp.md).

3. Direct instantiation: If an entry is an object, Claude immediately uses that definition to launch the server, ignoring any external configuration files.

This precedence system ensures that subagent-specific overrides always win, making it possible to customize shared servers for specific use cases without modifying the project-wide defaults.

Practical Implementation Examples

Referencing a Shared Server from .mcp.json

The following subagent definition references a server named playwright that must exist in the project's .mcp.json file:

# .claude/agents/playwright-agent.md

---
name: playwright-agent
description: Automate browser UI tests using the shared Playwright MCP server.
tools: Read, Write, Edit
model: sonnet
mcpServers:
  - playwright          # ← string, resolved from .mcp.json

---

# Agent logic follows...

Claude resolves the string "playwright" by searching the configuration hierarchy and launches the server using the command defined in the external file.

Defining a Server Inline in Front Matter

For a self-contained agent that ships its own server configuration, use the inline object format:

# .claude/agents/playwright-inline-agent.md

---
name: playwright-inline-agent
description: Same as above but ships its own Playwright definition.
tools: Read, Write, Edit
model: sonnet
mcpServers:
  - playwright:
      command: npx
      args: ["-y", "@playwright/mcp"]
---

# Agent logic follows...

This configuration bypasses .mcp.json entirely and launches the Playwright server directly using the embedded parameters.

Project-Wide Configuration File

The .mcp.json file at the project root serves as the central registry for shared servers referenced by name:

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

This file, referenced in best-practice/claude-mcp.md (lines 48-66), allows teams to version-control server definitions and update them in one location for all referencing subagents.

Choosing Between Centralized and Inline Configuration

Reusability: Server name references excel when multiple agents need the same tool. Updates to .mcp.json propagate to all agents automatically. Inline configurations require editing each agent file individually when parameters change.

Version control: Centralized definitions in .mcp.json live with the repository code, ensuring consistency across team members. Inline configurations make individual agents self-documenting but scatter server definitions across multiple files.

Scope and privacy: Use server name references for project-wide shared infrastructure like Playwright automation or Context7 documentation indexing. Use inline configurations for experimental or private servers that should only be visible to a single agent.

Secret handling: Both methods support environment variable expansion using ${VAR} syntax. Centralized configurations in .mcp.json offer a single location to manage environment variable references for secrets, while inline configurations require careful attention to variable syntax within YAML front matter.

Summary

• Server name references (strings) look up definitions in .mcp.json following the Subagent > Project > User hierarchy.
• Inline configurations (objects) embed complete server definitions directly in the subagent front matter, bypassing external files.
• The mcpServers field in best-practice/claude-subagents.md accepts both formats in the same array, allowing hybrid approaches.
• Project-wide .mcp.json configurations promote consistency and easier maintenance for shared team resources.
• Inline configurations provide portability and self-documentation for specialized or experimental agents.

Frequently Asked Questions

Can I override a project-wide MCP server in a specific subagent?

Yes. According to the hierarchy documented in best-practice/claude-mcp.md, subagent configurations take precedence over project and user settings. Define a server with the same name in your agent's front matter using either an inline object or a string reference that resolves to a different configuration at the subagent level.

How do I handle environment variables in inline MCP configurations?

Both approaches support environment variable expansion using ${VAR} syntax. In inline configurations, ensure you properly escape the variable syntax within the YAML front matter. For centralized management, define environment variables in .mcp.json where they can be referenced by multiple agents without repetition.

What happens if a server name reference cannot be found in .mcp.json?

If Claude Code encounters a string in mcpServers that does not exist in the merged configuration hierarchy (Subagent, Project, or User levels), the subagent initialization will fail with a resolution error. The system requires all string references to resolve to valid server definitions in one of the configuration layers.

Are inline MCP server definitions version controlled differently?

Inline definitions live directly within the subagent markdown files (.claude/agents/*.md), so they version control with the agent logic itself. This creates a tight coupling between the agent and its tools but eliminates the risk of external configuration drift. Centralized .mcp.json definitions separate infrastructure from agent logic, requiring coordination between the two files during updates.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}