Building Agents with CrewAI and MCP

Hands-on tutorial from Data Makers Fest 2026.

Build a multi-agent fraud detection system that investigates domains and UK companies, then synthesises the findings into a risk report.

What you'll learn

• How to design effective agents using the role–goal–backstory framework
• How to write tasks with clear scope, deliverables, and structured outputs
• How to give agents capabilities through tools, skills, and MCP servers
• How to assemble agents and tasks into a crew with sequential orchestration
• How to build a full CrewAI project

Prerequisites

• Python 3.11+
• A LiteLLM API key (provided by the workshop organisers)
• A Companies House API key (free)

Setup

Start with notebook 00_setup.ipynb — it walks you through every step from scratch, including Python installation, dependency setup, and verification.

Quick summary for experienced users:

1. Install uv if you don't have it:

pip install uv

2. Clone the repo and install dependencies:

git clone <repo-url>
cd <repo-folder>
uv sync

3. Create your .env file with your API keys:

OPENAI_API_KEY=<your-litellm-key>
OPENAI_API_BASE=http://34.254.232.70:4000/
COMPANIES_HOUSE_API_KEY=...

4. Register the Jupyter kernel: (Optional, if you prefer other tools/IDEs like VSCode)

uv run python -m ipykernel install --user --name=data-makers --display-name "Data Makers Tutorial"

Tutorial notebooks

Work through these in order. Each notebook builds on the previous one.

#	Notebook	What it covers
00	00_setup.ipynb	Full environment setup from scratch — Python, uv, dependencies, .env configuration, kernel registration, and connectivity verification
01	01_agent_design.ipynb	The role–goal–backstory framework, agent attributes (llm, tools, max_iter, verbose, etc.), creating agents from YAML vs code, designing agents for collaboration, and prototyping with kickoff()
02	02_tasks_and_agents.ipynb	Task design (description vs expected_output), task attributes (context, output_file, output_pydantic, markdown, guardrail), wiring tasks to agents, and running a mini crew
03a	03a_tools_and_skills.ipynb	Creating tools with BaseTool and the @tool decorator, skills as reusable prompt context (SKILL.md), and combining tools with skills for stronger agents
03b	03b_building_an_mcp_server.ipynb	MCP theory (client-server model, capabilities), building a phishing enrichment MCP server from scratch, wiring tools with list_tools and call_tool, and connecting the server to a CrewAI agent via MCPServerStdio
04	04_crews.ipynb	Crew attributes and process types, building a crew with @CrewBase and YAML config, before_kickoff / after_kickoff hooks, and running a full three-agent crew end to end

The final crew (src/risk_intelligence_crew/)

The src/ directory contains the final version of everything explored in the notebooks.

Agents

Defined in config/agents.yaml:

Agent	Role
domain_intelligence_analyst	Assesses domain legitimacy via WHOIS, DNS, and certificate transparency
corporate_registry_investigator	Investigates UK companies through Companies House data
fraud_risk_synthesiser	Combines signals from both analyses into a final risk verdict

Tasks

Defined in config/tasks.yaml, executed sequentially:

1. domain_assessment_task — WHOIS + DNS + cert transparency analysis of the target domain
2. company_lookup_task — Searches Companies House for the entity
3. company_deep_dive_task — Full profile, officers, filings, PSCs, and charges review
4. officer_network_task — Maps each officer's other company appointments and flags patterns
5. risk_report_task — Synthesises all findings into a combined risk rating

Each task produces a typed Pydantic output (defined in models.py) and writes a markdown report to outputs/.

Tools

Tool	Source	What it does
whois_lookup	tools/domain_tools.py	WHOIS registration data (age, registrar, privacy)
dns_lookup	tools/domain_tools.py	DNS records + SPF/DMARC detection
cert_transparency_lookup	tools/domain_tools.py	Certificate transparency logs via crt.sh
virustotal_domain_report	notebooks/tools/virustotal_tool.py	VirusTotal v3 domain reputation report
companies_house_search	tools/companies_house_tool.py	Company name search
companies_house_profile	tools/companies_house_tool.py	Full company profile
companies_house_officers	tools/companies_house_tool.py	Officer list with IDs
companies_house_filing_history	tools/companies_house_tool.py	Recent filings
companies_house_pscs	tools/companies_house_tool.py	Persons with significant control
companies_house_charges	tools/companies_house_tool.py	Mortgages and secured debts
companies_house_officer_appointments	tools/companies_house_tool.py	Other companies an officer is linked to

Skills

The corporate_registry_investigator agent uses a skill (skills/companies-house-investigation/) that injects investigative methodology into its prompt — covering how to run the company lookup, deep dive, and officer network tasks, plus a red flags scoring guide for deriving risk ratings.

Running the crew

uv run run-crew

This runs the default investigation defined in main.py. Edit the inputs dict there to change the target entity and domain.

Project structure

├── notebooks/                          # Tutorial notebooks (start here)
│   ├── 00_setup.ipynb
│   ├── 01_agent_design.ipynb
│   ├── 02_tasks_and_agents.ipynb
│   ├── 03a_tools_and_skills.ipynb
│   ├── 03b_building_an_mcp_server.ipynb
│   ├── 04_crews.ipynb
│   ├── config/                         # YAML configs used by notebook 04
│   ├── skills/                         # Example skill used by notebook 03a
│   ├── tools/                          # CrewAI tools used by notebooks 03a and 04
│   └── mcp_server/                     # MCP server and async tools used by notebook 03b
│       ├── __init__.py
│       ├── server.py
│       ├── whois_lookup.py
│       ├── dns_lookup.py
│       ├── cert_transparency.py
│       └── virustotal.py
├── src/risk_intelligence_crew/         # Production crew
│   ├── config/                         # Agent and task YAML definitions
│   ├── tools/                          # Domain and Companies House tools
│   ├── skills/                         # Companies House investigation skill
│   ├── models.py                       # Pydantic output models
│   ├── crew.py                         # Crew definition (@CrewBase)
│   └── main.py                         # CLI entry point (run-crew)