Claude Code Agents & MCP: The Complete Developer Guide

Claude Code isn't just an AI coding assistant - it's an agentic system that can delegate tasks, run parallel operations, and connect to external tools. This guide covers everything from basic subagents to building custom MCP integrations.

🤖

What You'll Learn

• Use built-in agents for faster codebase exploration
• Connect to databases, GitHub, and other tools via MCP
• Create custom agents for your specific workflows

What Are Agents?

Agents in Claude Code are specialized subprocesses that handle complex tasks autonomously. Instead of doing everything in one conversation, Claude can spin up focused agents for specific jobs - then bring results back to you.

🔍

Explore

Fast codebase search using Haiku (~1/3 cost)

📋

Plan

Research and gather context before implementation

💻

Bash

Execute terminal commands in isolated context

🟢 Beginner: Getting Started

Built-in Agents

Claude Code automatically delegates to these agents when appropriate:

Agent	Model	Best For
Explore	`haiku` (fast, ~1/3 cost)	Finding files, searching code, understanding patterns
Plan	Main model (`opus` in opusplan)	Gathering context before presenting implementation plans
Bash	Inherits from main	Running commands in isolated context
General-purpose	Inherits from main	Complex multi-step tasks requiring exploration AND edits

Essential Commands

# Run a task in the background (keeps main conversation free)
Ctrl+B or say "Run this in the background"

# View all running tasks
/tasks

# Switch models mid-session
/model opus or /model haiku

# Explicitly use the Explore agent
"Use the Explore agent to find all API endpoints"

# Run multiple searches in parallel
"Search for auth, database, and API patterns in parallel"

💡

Pro Tip: Save Context

Use the Explore agent for research tasks. Verbose output stays in the subagent, keeping your main conversation clean.

🎯 Choosing the Right Model

Claude Code supports multiple models optimized for different tasks. Understanding when to use each can significantly impact your productivity and costs.

Model Aliases

Alias	Model	Best For
`sonnet`	Sonnet 4.5	Daily coding tasks, balanced performance (recommended default)
`opus`	Opus 4.5	Complex reasoning, architecture decisions, difficult bugs
`haiku`	Haiku 4.5	Fast simple tasks, codebase exploration, ~1/3 cost of Sonnet
`opusplan`	Opus → Sonnet	Hybrid mode: Opus for planning, auto-switches to Sonnet for execution
`sonnet[1m]`	Sonnet (1M context)	Long sessions, very large codebases (API/Console users)

Decision Guidelines

✓ Use Haiku When

• Exploring/searching codebases
• Running simple automated tasks
• Quick file lookups and searches
• Cost is a primary concern

✓ Use Opus When

• Designing system architecture
• Debugging complex issues
• Multi-file refactoring
• Critical code reviews

⚡

Pro Tip: opusplan Mode

The opusplan alias gives you the best of both worlds: Opus's superior reasoning for planning and architecture, then automatic switching to Sonnet's efficiency for code generation. Start with claude --model opusplan.

Model Commands

# Switch models mid-session
/model sonnet
/model opus

# Start with a specific model
claude --model opus

# Use hybrid mode (Opus plans, Sonnet executes)
claude --model opusplan

# Check your current model
/status

# Set default model via environment variable
export ANTHROPIC_MODEL=sonnet

# Set model for subagents specifically
export CLAUDE_CODE_SUBAGENT_MODEL=haiku

📄 CLAUDE.md: Your Agent's Constitution

The CLAUDE.md file at your project root acts as a persistent "constitution" for all Claude Code sessions. Boris Cherny (author of Programming TypeScript) uses this approach to run 5 parallel Claudes on complex tasks.

What to Include

Project Context

• Project overview and purpose
• Key directories and their roles
• Important dependencies

Standards & Rules

• Coding conventions
• Testing requirements
• Things to avoid

Example CLAUDE.md

# Project: E-commerce API

## Overview
Node.js backend with PostgreSQL. Uses Express + TypeScript.

## Key Directories
- src/routes/ - API endpoints
- src/services/ - Business logic
- src/models/ - Database models

## Rules
- Always write tests for new endpoints
- Use camelCase for variables, PascalCase for types
- Never commit .env files
- Run npm test before pushing

🟡 Intermediate: MCP Servers

What is MCP?

Model Context Protocol (MCP) is an open standard that connects Claude Code to external tools and data sources. Think of it as plugins for AI - query databases, integrate with GitHub, access Figma designs, and more.

Why MCP Matters

✓ Query your database directly from Claude Code
✓ Create GitHub PRs, read issues, manage repos
✓ Access error monitoring from Sentry
✓ Pull designs from Figma for implementation

Most Useful MCP Servers

Server	Use Case	Setup Command
GitHub	PRs, issues, repos	`claude mcp add github`
Context7	Up-to-date library docs	`claude mcp add context7 -- npx @context7/mcp`
PostgreSQL	Query databases	`claude mcp add db -- npx @bytebase/dbhub`
Puppeteer	Browser automation, screenshots	`claude mcp add puppeteer`
Sentry	Error monitoring	`claude mcp add sentry`
Figma	Design-to-code	`Available in MCP registry`
Slack	Message teams	`Available in MCP registry`

💼

Real-World Impact: Block (Square)

Block reported 75% time savings on engineering tasks using Claude Code with MCP integrations for database queries and GitHub workflows.

MCP Commands

# Add a new MCP server
claude mcp add <server-name>

# List all configured servers
claude mcp list

# Remove a server
claude mcp remove <server-name>

# Authenticate or debug MCP
/mcp

# Example: Add PostgreSQL with connection string
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://user:pass@localhost/mydb"

⚠️

Configuration Scopes

Local (default): Personal, one project. Project: Saved to .mcp.json, shared with team. User: Available across all projects.

Troubleshooting MCP

MCP connections can fail silently. Use these tools to debug:

# Start Claude Code with MCP debugging enabled
claude --mcp-debug

# In-session: authenticate or check MCP status
/mcp

# View configured servers and their status
claude mcp list

🔧

Common Issues

• Auth failures: Run /mcp to re-authenticate
• Server not starting: Check that required tools (npx, docker) are installed
• Tools not appearing: Restart Claude Code after adding new MCP servers

🔴 Advanced: Custom Agents

Create Your Own Agents

Store custom agent definitions in .claude/agents/ (project) or ~/.claude/agents/ (user-level). Each agent gets its own system prompt, tool restrictions, and permission mode.

Example: Code Reviewer Agent

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Grep, Glob
permissionMode: plan
---

You are a senior code reviewer. Analyze code for:

## Checklist
- Code clarity and readability
- Performance concerns
- Security vulnerabilities
- Proper error handling
- Test coverage gaps

Be specific. Reference line numbers. Suggest fixes.

Example: Database Reader (with Hooks)

# .claude/agents/db-reader.md
---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      command: "./scripts/validate-readonly-query.sh"
---

You can only run SELECT queries. Never modify data.
Always explain what the query does before running it.

Example: Test Runner Agent

# .claude/agents/test-runner.md
---
name: test-runner
description: Runs tests and reports failures
tools: Bash, Read, Grep
model: haiku
---

Run tests and analyze failures. For each failure:
1. Show the error message
2. Identify the root cause
3. Suggest a fix

Use npm test or pytest based on the project.

Agent Priority Order

When multiple agents match, Claude uses this priority:

1 CLI flag --agents (session-only, highest priority)
2 Project .claude/agents/ (version controlled)
3 User ~/.claude/agents/ (all projects)
4 Plugins (lowest priority)

🔒

Security Best Practices

• Limit MCP servers: Select 2-3 targeted MCPs, avoid over-provisioning
• Use permissionMode: Set to plan for sensitive operations
• Validate with hooks: Add PreToolUse hooks to validate dangerous commands
• Read-only by default: Create db-reader agents that can only run SELECT queries

Quick Reference Card

Keyboard Shortcuts

Send to background Ctrl+B
View tasks /tasks
Manage agents /agents
MCP management /mcp

Common Patterns

• Use Explore for research to save context
• Run searches in parallel for speed
• Create read-only agents for safety
• Share agents via .claude/agents/

Resources & Links

Claude Code Documentation

Official getting started guide

Subagents Documentation

Create and manage custom agents

MCP Documentation

Connect to external tools and databases

MCP Server Registry

100+ official MCP servers to explore

Build Your Own MCP Server

MCP SDK quickstart guide

Start Building with Claude Code

Use agents and MCP servers to supercharge your development workflow. Install Claude Code and try it today.

Get Claude Code Read the Docs