How to Integrate ZenRows with Mastra

​

What Is Mastra?

​

Why Connect ZenRows to Mastra?

• Ship agents that access any site: Mastra agents call tools to do their work. Without ZenRows, any page protected by Cloudflare, DataDome, or similar systems returns a blocked or empty response. Add ZenRows and your agents bypass the blocks to fetch the actual content every time.
• Structured output, ready for your app: ZenRows returns clean Markdown or JSON instead of raw HTML. Mastra agents receive structured, LLM-friendly data, resulting in less post-processing, fewer tokens, and cleaner output to pass downstream.
• Give any model on Mastra’s router real-time web access: Mastra supports 3,000+ models from OpenAI, Anthropic, Google, Groq, Mistral, and more. ZenRows MCP enables real-time web access regardless of which model your agent uses.
• Multi-agent workflows with live web data: Mastra supports supervisor agents that coordinate subagents. Each subagent can call ZenRows independently, and a coordinator synthesizes the results.
• Ship web data features into your product without building a scraping layer: With ZenRows MCP, your agent calls a tool and gets structured content back. No scraping infrastructure to maintain and no browser pool to spin up alongside your app.
• Keep your RAG pipelines current: Connect ZenRows with Mastra and your RAG ingestion workflow can pull live content from any source on demand, including pages behind bot protection and heavy JavaScript rendering that a plain HTTP fetch would never reach.

​

What You Can Build with Mastra and ZenRows

• A competitive pricing monitor shipped inside your product: Build an agent your users can query that scrapes live pricing across sites via ZenRows and returns a structured answer. Deploy it as part of your Next.js or Express app using Mastra’s server adapters.
• An e-commerce research workflow: Chain a multi-step Mastra workflow to scrape a product category page, extract product names and prices, enrich with reviews from a second page, run a structured-output step to rank by value, and return a clean JSON response to your frontend.
• A sales intelligence agent: Build an internal copilot that researches a prospect before a call, scraping their company site, recent news, and job postings via ZenRows, and returns a structured brief via your Slack channel or internal tool.
• Content automation for a CMS: Set up a Mastra workflow that scrapes a set of sources on a schedule, extracts key content, runs it through a summarization or transformation step, and writes structured output directly to your CMS or knowledge base.
• A data analysis agent with live market data: Extend Mastra’s text-to-SQL and data analysis agent template with ZenRows to pull live market data, competitor pricing, or industry benchmarks from the web, then feed it into the analysis pipeline alongside your internal database.

​

Prerequisites

• Node.js 18+ installed.
• A Mastra project scaffolded via npm create mastra@latest, which creates the full project structure (src/mastra/agents, tools, workflows, index.ts) that you’ll build on top of.
• An Anthropic API key (or your preferred provider).
• A ZenRows API key from the ZenRows Playground.

npm create mastra@latest

​

Setup

npm install @mastra/mcp@latest @ai-sdk/anthropic

// npm install @mastra/mcp@latest
import { MCPClient } from '@mastra/mcp'

// Connect to the MCP server using the MCPClient class
export const zenrowsClient = new MCPClient({
  id: 'zenrows-mcp-client',
  servers: {
    zenrows: {
      command: 'npx',
      args: ['-y', '@zenrows/mcp'],
      env: {
        ZENROWS_API_KEY: process.env.ZENROWS_API_KEY!,
      },
    },
  },
})

ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY
ZENROWS_API_KEY=YOUR_ZENROWS_API_KEY

export const zenrowsClient = new MCPClient({
  id: 'zenrows-mcp-client',
  servers: {
    zenrows: {
      url: new URL('https://mcp.zenrows.com/mcp'),
      requestInit: {
        headers: {
          Authorization: `Bearer ${process.env.ZENROWS_API_KEY}`,
        },
      },
    },
  },
})

// npm install @mastra/mcp@latest @ai-sdk/anthropic
import { Agent } from '@mastra/core/agent'
import { anthropic } from '@ai-sdk/anthropic'
import { zenrowsClient } from '../mcp/zenrows-client.js'

export const researchAgent = new Agent({
  id: 'research-agent',
  name: 'Research Agent',
  instructions: `You are a web research assistant. Use ZenRows tools to
    scrape pages and extract structured data. Always return clean,
    structured results.`,
  model: anthropic('claude-sonnet-4-6'),
  tools: await zenrowsClient.listTools(),
})

// npm install @mastra/mcp@latest @ai-sdk/anthropic
import { Agent } from '@mastra/core/agent'
import { anthropic } from '@ai-sdk/anthropic'
import { zenrowsClient } from '../mcp/zenrows-client.js'

// Fetch the list of tools from the ZenRows MCP server
const allTools = await zenrowsClient.listTools()

export const researchAgent = new Agent({
  id: 'research-agent',
  name: 'Research Agent',
  instructions: `You are a web research assistant. Use ZenRows tools to
    scrape pages and extract structured data. Always return clean,
    structured results.`,
  model: anthropic('claude-sonnet-4-6'),
  // Only include zenrows_scrape if it's available
  tools: allTools['zenrows_scrape'] ? { zenrows_scrape: allTools['zenrows_scrape'] } : {},
})

import { researchAgent } from './agents/research-agent.js'

// Add researchAgent to your existing Mastra instance
export const mastra = new Mastra({
  agents: { researchAgent },
})

npm run dev

Scrape https://www.scrapingcourse.com/antibot-challenge and summarize the page.

I'll scrape that page for you and provide a summary.

[zenrows_scrape]

Summary

The page at https://www.scrapingcourse.com/antibot-challenge is a test page designed to
challenge web scrapers with anti-bot protection.

Key Content:
- Site: Scraping Course (scrapingcourse.com)
- Page Title: "Antibot Challenge"
- Main Message: "You bypassed the Antibot challenge! :D"

This appears to be a training/testing page that implements anti-bot measures.
[Truncated for brevity]

// Import .env config and the mastra instance from the index file
import 'dotenv/config'
import { mastra } from '../mastra/index.js'

// Get the research agent from the mastra instance
const agent = mastra.getAgentById('research-agent')

// Generate a response using a research query
const response = await agent.generate(
  'Get the top 5 deals on https://www.amazon.com/s?k=headset based on product price and rating.'
)

console.log(response.text)

npx tsx src/scripts/test-agent.ts

import { researchAgent } from './agents/research-agent.js'
import { registerApiRoute } from '@mastra/core/server'

export const mastra = new Mastra({
  agents: { researchAgent },
  server: {
    apiRoutes: [
      registerApiRoute('/research', {
        method: 'POST',
        handler: async (c: any) => {
          const mastra = c.get('mastra')
          const agent = mastra.getAgentById('research-agent')
          const { prompt } = await c.req.json()
          const response = await agent.generate(prompt)
          return c.json({ result: response.text })
        },
      }),
    ],
  },
})

curl -X POST http://localhost:4111/research \
  -H "Content-Type: application/json" \
  -d "{\"prompt\": \"Scrape the top headlines from news.ycombinator.com and summarize the top 3 stories in one paragraph.\"}"

​

Dynamic Tools for Multi-Tenant Apps

import { MCPClient } from '@mastra/mcp'

registerApiRoute('/research-user', {
  method: 'POST',
  handler: async (c: any) => {
    const { prompt, apiKey } = await c.req.json()
    const userMcp = new MCPClient({
      servers: {
        zenrows: {
          url: new URL('https://mcp.zenrows.com/mcp'),
          requestInit: {
            headers: {
              Authorization: `Bearer ${apiKey}`,
            },
          },
        },
      },
    })
    const mastra = c.get('mastra')
    const agent = mastra.getAgentById('research-agent')
    const response = await agent.generate(prompt, {
      toolsets: await userMcp.listToolsets(),
    })
    await userMcp.disconnect()
    return c.json({ result: response.text })
  },
}),

curl -X POST http://localhost:4111/research-user \
  -H "Content-Type: application/json" \
  -d "{\"prompt\": \"Scrape https://www.scrapingcourse.com/antibot-challenge and summarize the page.\", \"apiKey\": \"YOUR_ZENROWS_API_KEY\"}"

​

Troubleshooting

​

This Site Can’t Be Reached or localhost:4111 Unreachable

npm run dev

​

500 Internal Server Error on Custom Routes

​

Could Not Find Config for Provider Anthropic Error

npm install @ai-sdk/anthropic

import { anthropic } from '@ai-sdk/anthropic'

// Do not use 'anthropic/claude-sonnet-4-6'
// Use this instead:
model: anthropic('claude-sonnet-4-6'),

​

Prompt Is Too Long Error

const allTools = await zenrowsClient.listTools()

export const researchAgent = new Agent({
  id: 'research-agent',
  name: 'Research Agent',
  instructions: `You are a web research assistant. Use ZenRows tools to
    scrape pages and extract structured data. Always return clean,
    structured results.`,
  model: anthropic('claude-sonnet-4-6'),
  tools: allTools['zenrows_scrape'] ? { zenrows_scrape: allTools['zenrows_scrape'] } : {},
})

model: anthropic('claude-opus-4-6'),

​

Cannot Find Name ‘process’ or Relative Import Path Errors

{
  "compilerOptions": {
    "types": ["node"]
  }
}

​

ZenRows Tools Not Appearing on the Agent

• Confirm @mastra/mcp is installed: npm list @mastra/mcp.
• Check that ZENROWS_API_KEY is set in your .env and that dotenv is loading it.
• When running scripts directly with npx tsx, add import 'dotenv/config' at the top of the file. The dev server loads .env automatically, but standalone scripts don’t.
• Make sure await zenrowsClient.listTools() is called at the module level in research-agent.ts, outside the Agent constructor. The await is required and must be at the top level of the file.

​

Authentication Error from ZenRows

​

Workflow Step Not Receiving ZenRows Output

​

Further Reading

• Mastra MCP Overview
• Mastra Agents
• Mastra Workflows
• MCPClient Reference
• Dynamic Tools for Multi-Tenant Apps
• ZenRows MCP Documentation

​

Frequently Asked Questions

export const zenrowsClient = new MCPClient({
    servers: {
        zenrows: {
            command: 'npx',
            args: ['-y', '@zenrows/mcp'],
            env: {
            ZENROWS_API_KEY: process.env.ZENROWS_API_KEY!,
            },
            requireToolApproval: true,
        },
    },
})

export const mcpClient = new MCPClient({
    id: 'multi-mcp-client',
    servers: {
        zenrows: {
            command: 'npx',
            args: ['-y', '@zenrows/mcp'],
            env: {
            ZENROWS_API_KEY: process.env.ZENROWS_API_KEY!,
            },
        },
        github: {
            command: 'npx',
            args: ['-y', '@modelcontextprotocol/server-github'],
            env: {
            GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN!,
            },
        },
    },
})