Claude Code Subagents, MCP Tools, and Web Search: A Practical Guide for SMEs

If you’re running AI locally on your own hardware, Claude Code’s subagent system — combined with the Model Context Protocol (MCP) tool ecosystem — is the biggest productivity leap since autocomplete. We’ve been running subagents in production for our own consulting work and for Apprendere’s Docebo deployments. Here’s what we’ve learned, what works, and where the sharp edges are.

What Are Subagents?

Subagents are specialized AI assistants that Claude Code can spawn in their own context window. Each subagent has a focused role, its own set of tools, and its own conversation history — isolated from the main conversation but able to report back results.

Think of it like this: if Claude Code is a senior developer, subagents are junior developers you can delegate specific tasks to. You wouldn’t ask a senior dev to write unit tests, review documentation, and fix a CSS bug simultaneously — you’d delegate. Subagents let you do the same thing with AI.

Built-in Subagents

Claude Code ships with three built-in subagents:

Subagent	Model	Tools	Best For
Explore	Haiku (fast, cheap)	Read-only: Read, Grep, Glob, LS	Research, codebase exploration, finding files
Plan	Haiku	Read-only	Architecture planning, approach evaluation
General	Sonnet (full)	All tools	Multi-step implementation, complex tasks

Custom Subagents

The real power comes from custom subagents. You define them as Markdown files in .claude/agents/:

---
name: security-reviewer
description: Reviews code for security vulnerabilities, OWASP compliance, and production reliability
model: haiku
tools:
  - Read
  - Grep
  - Glob
  - LS
  - NotebookRead
permissionMode: default
---

You are a security review specialist. When reviewing code, check for:

1. **Injection vulnerabilities**: SQL injection, XSS, command injection
2. **Authentication flaws**: Hardcoded credentials, weak session management
3. **Data exposure**: Sensitive data in logs, missing encryption, CORS misconfigurations
4. **Dependency risks**: Known CVEs, outdated packages, unnecessary dependencies

Provide findings as a structured list with severity (Critical/High/Medium/Low), file location, and remediation steps.

This agent lives in .claude/agents/security-reviewer.md and Claude Code can invoke it with the Agent tool whenever a security review is needed.

MCP Tools: The Game-Changer for Local AI

The Model Context Protocol (MCP) is how subagents connect to external data and services. In 2026, MCP servers are the standard way to give AI agents access to databases, APIs, file systems, and web search — all while running locally.

The mcpServers Frontmatter Field (March 2026)

The biggest MCP update for subagents is the mcpServers field in agent frontmatter. This lets you define MCP servers scoped to a specific subagent only — the main conversation never sees them:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

When the browser-tester subagent starts, it connects to the Playwright MCP server. When it finishes, the server disconnects. The main conversation has zero knowledge of Playwright’s tools — no context bloat, no security exposure.

MCP Servers We Use in Production

Server	Purpose	Token Overhead	Local?
@anthropic/mcp-filesystem	Read/write local files	~500	Yes
@playwright/mcp	Browser automation	~2,000	Yes
@anthropic/mcp-github	GitHub operations	~1,500	API
@anthropic/mcp-sqlite	SQLite queries	~800	Yes
Custom Ollama MCP	Local LLM inference	~300	Yes

The total context cost for running 5 MCP servers simultaneously is ~5,100 tokens — about 2% of a Sonnet context window. That’s negligible compared to the productivity gain.

Web Search in Claude Code

Claude Code’s web search integration (announced in the Ollama 0.19 release notes) gives subagents access to real-time information without leaving the local environment. Here’s how it works:

1. The search query is sent to a configured search provider (default: Google Programmable Search)
2. Results are summarized and injected into the subagent’s context
3. The subagent can cite sources in its response
4. No API key required if you’re using Ollama’s built-in search (it uses their public endpoint)

For SMEs running fully local, the key insight is that web search doesn’t require cloud LLM access. You can use it with local models:

---
name: market-researcher
description: Researches market data, competitor pricing, and regulatory changes
model: haiku
tools:
  - Read
  - WebSearch
  - WebFetch
---

You are a market research specialist. Use web search to find current data on:
- Competitor pricing and positioning
- Regulatory changes in the EU AI Act
- Market size and growth data for specific sectors
- Recent news affecting the client's industry

Always cite your sources with URLs.

Practical Subagent Patterns for SMEs

Pattern 1: Code Review Pipeline

Run three specialized reviewers in parallel on every pull request:

# .claude/agents/security-reviewer.md — (defined above)

# .claude/agents/perf-reviewer.md
---
name: perf-reviewer
description: Reviews code for performance issues, memory leaks, and scalability problems
model: haiku
tools:
  - Read
  - Grep
  - Glob
---
Check for: N+1 queries, missing pagination, unbounded queries, missing caching, blocking I/O in async code.

# .claude/agents/style-reviewer.md
---
name: style-reviewer
description: Reviews code for style consistency, naming conventions, and readability
model: haiku
tools:
  - Read
  - Grep
---
Check for: inconsistent naming, deep nesting, missing error handling, code duplication.

Then in your workflow: Claude, review this PR using security-reviewer, perf-reviewer, and style-reviewer in parallel.

Pattern 2: Documentation Generator

---
name: doc-writer
description: Generates documentation from code, following the project's documentation style
model: sonnet
tools:
  - Read
  - Write
  - Grep
  - Glob
mcpServers:
  - filesystem:
      type: stdio
      command: npx
      args: ["-y", "@anthropic/mcp-filesystem", "/path/to/docs"]
---

Generate documentation following the project's existing style. Read existing docs first for format reference.

Pattern 3: Compliance Auditor

For EU AI Act and GDPR compliance, a subagent that checks your codebase against regulatory requirements:

---
name: compliance-auditor
description: Audits code and configurations for EU AI Act and GDPR compliance
model: sonnet
tools:
  - Read
  - Grep
  - Glob
  - WebSearch
---

Check for:
- GDPR Article 25 (Privacy by Design): data minimization, purpose limitation, consent mechanisms
- EU AI Act risk classification: is the AI system high-risk? Are transparency requirements met?
- Data processing agreements, DPA records, consent logs
- Cross-border data transfer mechanisms (Standard Contractual Clauses)
- Right to explanation, right to erasure implementation

Known Issues and Workarounds (June 2026)

The subagent system is powerful but has sharp edges:

1. Plugin-defined subagents can’t access MCP tools (Issue #21560) — MCP servers defined in a plugin’s .mcp.json don’t propagate to plugin agents. Workaround: Define MCP servers in the agent’s own frontmatter.

2. OAuth-based MCP servers fail in plugin contexts — The authentication flow doesn’t complete when launched from a subagent. Workaround: Use API key-based authentication for MCP servers in subagents.

3. --agent flag doesn’t instantiate MCP when launching as main session (Issue #4476). Workaround: Start normally, then use the Agent tool to invoke subagents.

4. Context bloat with many MCP tools — If you connect 5+ MCP servers, the tool descriptions can consume 10K+ tokens. Workaround: Use the mcpServers frontmatter field to scope MCP servers to individual subagents rather than the main session.

5. Forked subagents (experimental) — The new fork isolation mode (v2.1.117+) inherits conversation history but has inconsistent behavior with long conversations. Workaround: Stick with worktree isolation for production use.

The Bottom Line for SMEs

Subagents + MCP is the most impactful AI productivity upgrade in 2026 for teams running local AI. Here’s why:

Before Subagents	After Subagents
One AI, one task at a time	Multiple AIs, parallel tasks
Full context window consumed by a single task	Focused context per agent
Manual context switching	Automatic delegation
No access to external tools	MCP connects to databases, browsers, APIs
Security review takes 30 minutes	Security review takes 2 minutes
Documentation is always stale	Documentation updates with every code change

For a Spanish SME running 3–5 AI-assisted developers, subagents typically save 8–12 hours per week on code review, documentation, and compliance auditing alone.

Want to set up subagents for your team? Contact us for a 15-minute consultation on local AI agent deployment.

Sources

• Claude Code Subagents Documentation
• MCP Servers in Agent Frontmatter (Issue #6915)
• Agent-Scoped MCP Configuration (Issue #4476)
• Plugin-Defined Subagents MCP Issue (#21560)
• Agent MCP Gateway Community Project