This lesson covers the foundation setup for a 5-agent Claude Code research system (Content Researcher, SEO/AEO Researcher, Competitive Analyzer, Technical Verifier, Content Gap Analyzer) built on MCP servers, a .claude directory structure, and business context profiles. It lets a content creator automate topic, keyword, and competitor research, cutting a 5-6 hour manual process to about 30 minutes.
What you will be able to do
- Set up the .claude directory structure (agents, research-profiles, research-outputs, build-logs) that every agent will use
- Configure Perplexity and Firecrawl MCP servers in .mcp.json so Claude Code can search and scrape for research
- Test that MCP connections work with a live Perplexity search and a Firecrawl scrape before building any agent
- Write business-context.md, content-strategy.md, and competitor-watchlist.md so agents research through your specific positioning and audience
- Plan the roles of 5 specialized research agents so each has its own MCP tools and output format instead of one generic assistant
Before you start
- Claude Code installed with a project workspace where you can create a .mcp.json file
- A Perplexity API key (no free tier, $5 per 1000 requests)
- A Firecrawl API key (free tier gives 500 pages per month)
- Comfort running terminal commands like mkdir and editing a JSON config file
Reference
| Step | What you do | Key detail | Time |
|---|---|---|---|
| 1. Directory structure | Create folders for the agent system | mkdir -p .claude/agents, .claude/research-profiles, .claude/research-outputs/{research-briefs,serp-analyses,competitive-reports}, .claude/build-logs |
1 min |
| 2. API keys | Get keys for the two MCP tools | Perplexity: perplexity.ai/api, no free tier, $5/1000 requests. Firecrawl: firecrawl.dev, free tier 500 pages/month | 5 min |
| 3. MCP config | Register both servers in .mcp.json at the project root |
Perplexity package @perplexity-ai/mcp-server, Firecrawl package firecrawl-mcp, each with its API key under env |
5 min |
| 4. Test connections | Restart Claude Code, then test each server | Ask it to run a Perplexity search and a Firecrawl scrape of a page; no startup errors is the good sign | 5 min |
| 5. Context profiles | Write the files agents read before researching | business-context.md (identity, mission, avatars, pain points, positioning), content-strategy.md (pillars, voice, topics to cover/avoid, formats, SEO/AEO approach), competitor-watchlist.md (competitors, monitoring focus, cadence) |
10 min |
| Total | Full foundation setup | Directory + keys + MCP config + testing + profiles | ~35 min |
Common errors and fixes
| What goes wrong | The fix |
|---|---|
Claude Code shows errors on startup after editing .mcp.json |
Treat a clean startup with no errors as the sign the config loaded correctly; if you see errors, recheck the server entries and API key placeholders |
API key placeholders left in .mcp.json |
Replace your-key-here for both Perplexity and Firecrawl with your actual keys before restarting Claude Code |
| Perplexity costs climb fast | There is no free tier ($5/1000 requests), so optimize which calls you actually make rather than querying freely |
| Context profiles get skipped to save time | Skipping this step is called out directly as something not to do. Without it, agents fall back to generic research, the same textbook-style answers you'd get from a plain ChatGPT or Claude chat |
Read the full walkthrough
The complete lesson, with screenshots and any downloads, is published on Substack as part of PubFlow OS Agents: Build Your AI Research Team.
Continue the course
Browse all lessons in the PubFlow OS Agents: Build Your AI Research Team course, or subscribe to the GenAI Unplugged newsletter to get new lessons in your inbox.
