Layer 5: Integration Layer (Tools & External Services)

What This Layer Is

The Integration Layer is how your marketing system interacts with the outside world. It consists of external services, APIs, and tools that enable capabilities like:

Web research and fact-checking
Content generation (images, videos)
Data gathering and scraping
Notifications and communication
Design asset creation

This is the only layer that reaches beyond the marketing system itself.

The Integration Principle

Tools ≠ Skills

Tools (Integration Layer) and Skills (Layer 4) work together but are fundamentally different:

Tools (Layer 5)	Skills (Layer 4)
What: External services (Perplexity, Firecrawl)	How: Methodologies and workflows
Purpose: Provide external capabilities	Purpose: Define how to use those capabilities
Examples: API calls, data fetching	Examples: Research frameworks, content structures
Ownership: Marketing Architect selects	Ownership: Infrastructure (core) + Marketing Architect (domain)

Example:

Tool: Perplexity API (web research service)
    ↓ leveraged by
Skill: "Conducting Market Research" (methodology for using Perplexity)
    ↓ used by
Agent: Brand Analyst (role that conducts research)

Tools Are Mapped to Skills

Skills know which tools they use. From “Conducting Market Research” skill (SKILL.md):

## Tools Used
- **Perplexity**: Web research, fact-checking, trend analysis
- **Firecrawl**: Competitor website scraping, content extraction

When an agent uses the skill, it automatically has access to these tools.

Available Tools (MCP Protocol)

The system uses Model Context Protocol (MCP) to integrate external tools.

Current Integrations

1. Perplexity (Research & Fact-Checking)

What it does:

Web research and information gathering
Fact-checking and verification
Trend analysis and market intelligence
Deep research with citations

Use cases:

Market research
Competitor analysis
Fact-checking claims
Finding industry data

Mapped to skills:

Conducting Market Research
Competitive Analysis
Fact-Checking Content

2. Firecrawl (Web Scraping & Content Extraction)

What it does:

Scrape competitor websites
Extract structured data from web pages
Monitor competitor changes
Batch content extraction

Use cases:

Analyzing competitor messaging
Tracking positioning changes
Extracting pricing data
Content audits

Mapped to skills:

Conducting Competitive Analysis
Market Research

3. Replicate (AI Models & Image Generation)

What it does:

Generate images for content
Access specialized AI models
Create visual assets
Run custom AI workflows

Use cases:

Blog post hero images
Social media graphics
Campaign visuals
Brand asset creation

Mapped to skills:

Creating Visual Content
Social Media Content Generation

4. Figma (Design Asset Creation) (Planned)

What it does:

Create and edit design assets
Access brand design system
Generate templates
Collaborate on visual work

Use cases:

Presentation slides
Marketing materials
Brand guidelines visualization

Mapped to skills:

Creating Presentations
Visual Brand Asset Management

5. Slack (Notifications & Communication) (Planned)

What it does:

Send notifications
Post updates to channels
Trigger workflows
Team communication

Use cases:

Notify when research complete
Post new content to review channel
Alert on campaign milestones

Mapped to skills:

Orchestrating Projects (notification workflows)

How Tools Are Used

Invocation Flow

1. Agent receives task requiring external data
   ↓
2. Agent uses relevant skill
   ↓
3. Skill specifies which tools to use
   ↓
4. Agent calls tool via MCP
   ↓
5. Tool executes (API call, scrape, generate, etc.)
   ↓
6. Tool returns data/results
   ↓
7. Agent processes using skill methodology
   ↓
8. Agent delivers output

Example: Competitive Analysis

Marketing Architect: "Analyze competitor X's positioning"
    ↓
Operations Manager: Delegates to Brand Analyst sub-agent
    ↓
Brand Analyst: Uses "Conducting Competitive Analysis" skill
    ↓
Skill specifies:
- Tool 1: Perplexity (research competitor info)
- Tool 2: Firecrawl (scrape competitor website)
    ↓
Brand Analyst executes:
1. Calls Perplexity: "Research Competitor X market position, recent news, strategy"
2. Calls Firecrawl: Scrapes competitor's homepage, about page, pricing page
    ↓
Perplexity returns: Articles, analysis, market positioning
Firecrawl returns: Website content, messaging, value props
    ↓
Brand Analyst: Processes data using competitive analysis framework (from skill)
    ↓
Returns: Structured competitive analysis report

The tools provide raw capability, the skill provides methodology.

Configuration & Management

MCP Configuration

Tools are configured via .mcp.json file:

{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "${PERPLEXITY_API_KEY}"
      }
    },
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "@firecrawl/mcp-server"],
      "env": {
        "FIRECRAWL_API_KEY": "${FIRECRAWL_API_KEY}"
      }
    },
    "replicate": {
      "command": "npx",
      "args": ["-y", "@replicate/mcp-server"],
      "env": {
        "REPLICATE_API_TOKEN": "${REPLICATE_API_TOKEN}"
      }
    }
  }
}

Marketing Architects don’t need to understand this deeply—infrastructure team provides templates.

Adding New Tools

Process:

Identify need (e.g., “We need to send Slack notifications”)
Find MCP-compatible tool (or request infrastructure team build integration)
Add to .mcp.json configuration
Map to relevant skills
Test integration

Marketing Architects control WHICH tools, infrastructure team handles HOW they integrate.

Tool Selection Guidelines

When to Add a New Tool

✅ Add a tool when:

You have a recurring need for external capability
No existing tool covers the use case
The tool provides strategic value
Integration cost is justified by usage

❌ Don’t add a tool when:

Existing tool can handle it (avoid redundancy)
One-off use case (not worth integration overhead)
Free alternatives exist within current tools
Security/compliance concerns

Evaluating Tools

Consider: 1. Capability

Does it solve a real need?
Is it better than alternatives?
Does it integrate well with skills?

2. Cost

API pricing structure
Usage limits
ROI based on frequency of use

3. Reliability

API uptime and stability
Rate limits and quotas
Error handling

4. Security

Data privacy policies
API key management
Compliance requirements (if handling customer data)

5. MCP Compatibility

Does an MCP server exist?
If not, can infrastructure team build one?
How complex is the integration?

Tool-to-Skill Mapping

Core Mappings

Research Skills:

Conducting Market Research
    → Perplexity (web research)
    → Firecrawl (competitor sites)

Analyzing Qualitative Data
    → (No external tools, processes existing data)

Content Skills:

Writing Brand-Consistent Content
    → (No external tools, uses strategy files)

Creating Visual Content
    → Replicate (image generation)
    → Figma (design assets) [planned]

Project Management Skills:

Orchestrating Projects
    → Slack (notifications) [planned]

Defining Mappings

In SKILL.md, specify tools:

## Tools Used
- **Perplexity**: Web research, fact-checking (required)
- **Firecrawl**: Competitor website analysis (optional, enhances research)

Agents using this skill will automatically invoke these tools when needed.

Security & Best Practices

API Key Management

✅ Best practices:

Store API keys in .env file (not committed to Git)
Use .env.example to document required keys (commit this)
Rotate keys periodically
Limit key permissions to minimum necessary

Example .env:

PERPLEXITY_API_KEY=your_key_here
FIRECRAWL_API_KEY=your_key_here
REPLICATE_API_TOKEN=your_key_here

Example .env.example (committed):

PERPLEXITY_API_KEY=
FIRECRAWL_API_KEY=
REPLICATE_API_TOKEN=

Cost Management

Monitor usage:

Set up billing alerts on tool dashboards
Track which skills use which tools most
Optimize queries to reduce API calls
Consider caching responses for repeated queries

Error Handling

When tools fail:

Skill should degrade gracefully
Agent should notify Marketing Architect
Fallback to alternative approach if possible

Example:

If Perplexity API fails:
→ Brand Analyst notifies: "Perplexity unavailable, proceeding with Firecrawl only"
→ Completes analysis with available data
→ Flags limitation in output

Ownership & Control

What Marketing Architects Own

✅ You control:

Which tools to integrate (based on your needs)
Tool selection (Perplexity vs alternatives)
API keys and accounts (you own the subscriptions)
Usage patterns (which skills use which tools)
Budget allocation (how much to spend on tools)

What Infrastructure Team Owns

✅ Infrastructure team controls:

How tools integrate (MCP server implementation)
Configuration structure (.mcp.json format)
Security best practices (key management guidelines)
Tool templates (pre-built integrations for common tools)

Common Questions

Q: Do I need to use all available tools?

No. Only integrate tools you actually need. Start minimal, add as requirements emerge. Recommended starter set:

Perplexity (research)
Firecrawl (competitor analysis)

Add others (Replicate, Figma, Slack) as specific needs arise.

Q: Can I use tools that aren’t MCP-compatible?

With infrastructure team help, yes. They can build custom MCP servers for tools you need. Easier path: Prioritize tools with existing MCP integrations.

Q: What if a tool’s API changes?

Infrastructure team handles this. MCP servers abstract the API details, so changes don’t break your skills. You might need to: Update skill documentation if tool capabilities change significantly.

Q: How do I know which tools a skill is using?

Check SKILL.md:

## Tools Used
- Perplexity
- Firecrawl

Or check during execution—agents will mention which tools they’re calling.

Q: Can different skills use the same tool?

Absolutely. Multiple skills can leverage the same tool for different purposes. Example:

“Conducting Market Research” uses Perplexity for market trends
“Fact-Checking Content” uses Perplexity for verification
“Competitive Analysis” uses Perplexity for competitor news

Q: What if I want to switch tools (e.g., Perplexity → alternative)?

Two steps:

Update .mcp.json configuration (swap tool)
Update skills that reference the old tool

Skills are isolated from tool implementation details, making swaps relatively easy.

Future Integrations (Roadmap)

Planned Additions

Short-term:

Slack - Notifications and team communication
Figma - Design asset creation

Medium-term:

CRM integrations - Customer data access
Analytics platforms - Performance data
Email platforms - Campaign deployment

Long-term:

Social media APIs - Direct posting
Ad platforms - Campaign management
Custom internal APIs - Proprietary data sources

Marketing Architects can request tools based on their needs.

What’s Next

Now that you understand all 5 layers, explore how they work together:

File Structure - How the layers map to directories
Plan/Implement Pattern - How work flows through the layers
Research Workflow - Layers in action for research
Content Generation - Layers in action for content

Or review the conceptual model:

Org Chart Model - The 5-layer framework

“Tools provide capability. Skills provide methodology. Together they create consistent, high-quality outputs.”

Getting Started

The Five Layers

System Architecture

Workflows

Reference

​Layer 5: Integration Layer (Tools & External Services)

​What This Layer Is

​The Integration Principle

​Tools ≠ Skills

​Tools Are Mapped to Skills

​Available Tools (MCP Protocol)

​Current Integrations

​1. Perplexity (Research & Fact-Checking)

​2. Firecrawl (Web Scraping & Content Extraction)

​3. Replicate (AI Models & Image Generation)

​4. Figma (Design Asset Creation) (Planned)

​5. Slack (Notifications & Communication) (Planned)

​How Tools Are Used

​Invocation Flow

​Example: Competitive Analysis

​Configuration & Management

​MCP Configuration

​Adding New Tools

​Tool Selection Guidelines

​When to Add a New Tool

​Evaluating Tools

​Tool-to-Skill Mapping

​Core Mappings

​Defining Mappings

​Security & Best Practices

​API Key Management

​Cost Management

​Error Handling

​Ownership & Control

​What Marketing Architects Own

​What Infrastructure Team Owns

​Common Questions

​Q: Do I need to use all available tools?

​Q: Can I use tools that aren’t MCP-compatible?

​Q: What if a tool’s API changes?

​Q: How do I know which tools a skill is using?

​Q: Can different skills use the same tool?

​Q: What if I want to switch tools (e.g., Perplexity → alternative)?

​Future Integrations (Roadmap)

​Planned Additions

​What’s Next

Layer 5: Integration Layer (Tools & External Services)

What This Layer Is

The Integration Principle

Tools ≠ Skills

Tools Are Mapped to Skills

Available Tools (MCP Protocol)

Current Integrations

1. Perplexity (Research & Fact-Checking)

2. Firecrawl (Web Scraping & Content Extraction)

3. Replicate (AI Models & Image Generation)

4. Figma (Design Asset Creation) (Planned)

5. Slack (Notifications & Communication) (Planned)

How Tools Are Used

Invocation Flow

Example: Competitive Analysis

Configuration & Management

MCP Configuration

Adding New Tools

Tool Selection Guidelines

When to Add a New Tool

Evaluating Tools

Tool-to-Skill Mapping

Core Mappings

Defining Mappings

Security & Best Practices

API Key Management

Cost Management

Error Handling

Ownership & Control

What Marketing Architects Own

What Infrastructure Team Owns

Common Questions

Q: Do I need to use all available tools?

Q: Can I use tools that aren’t MCP-compatible?

Q: What if a tool’s API changes?

Q: How do I know which tools a skill is using?

Q: Can different skills use the same tool?

Q: What if I want to switch tools (e.g., Perplexity → alternative)?

Future Integrations (Roadmap)

Planned Additions

What’s Next