Skip to content

Commit 20b455d

Browse files
MQ37MQ37
committed
add mastra mcp agent integration docs
1 parent 07e9623 commit 20b455d

File tree

1 file changed

+222
-0
lines changed

1 file changed

+222
-0
lines changed

‎sources/platform/integrations/ai/mastra.md‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
---
2+
title: Mastra integration
3+
sidebar_label: Mastra
4+
description: Learn how to build AI Agents Mastra using Apify MCP server
5+
sidebar_position: 1
6+
slug: /integrations/mastra
7+
---
8+
9+
**Learn how to build AI Agents with Mastra and Apify MCP server.**
10+
11+
---
12+
13+
## What is Mastra
14+
15+
[Mastra](https://mastra.ai) is an open-source TypeScript framework for building AI applications efficiently. It provides essential tools like agents, workflows, retrieval-augmented generation (RAG), integrations, and evaluations. Supporting any LLM (e.g., GPT-4, Claude, Gemini), it simplifies development with a unified interface via the Vercel AI SDK. You can run it locally or deploy it to a serverless cloud like [Apify](https://apify.com).
16+
17+
:::note Explore Mastra
18+
See the [Mastra docs](https://mastra.ai/docs) for more.
19+
:::
20+
21+
## What MCP server
22+
23+
An [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server exposes specific data sources or tools to agents via a standardized protocol. It acts as a bridge, connecting large language models (LLMs) to external systems like databases, APIs, or local filesystems. Built on a client-server architecture, MCP servers enable secure, real-time interaction, allowing agents to fetch context or execute actions without custom integrations. Think of it as a modular plugin system for agents, simplifying how they access and process data. Apify provides [Actors MCP Server](https://apify.com/apify/actors-mcp-server) to expose [Apify Actors](https://docs.apify.com/platform/actors) from the [Apify Store](https://apify.com/store) as tools via the MCP protocol.
24+
25+
## How to use Apify with Mastra via MCP
26+
27+
This guide demonstrates how to integrate Apify Actors with Mastra by building an agent that uses the [RAG Web Browser](https://apify.com/apify/rag-web-browser) Actor to search Google for TikTok profiles and the [TikTok Data Extractor](https://apify.com/clockworks/free-tiktok-scraper) Actor to extract and analyze data from the TikTok profiles via MCP.
28+
29+
:::note MCP tools
30+
31+
Since we are using the MCP server, we do not have to make any code changes and can dynamically change the Actors provided to the agent by modifying the startup request to the MCP server.
32+
33+
:::
34+
35+
### Prerequisites
36+
37+
- **Apify API token**: To use Apify Actors in CrewAI, you need an Apify API token. Learn how to obtain it in the [Apify documentation](https://docs.apify.com/platform/integrations/api).
38+
- **OpenAI API key**: To power the agents in CrewAI, you need an OpenAI API key. Get one from the [OpenAI platform](https://platform.openai.com/account/api-keys).
39+
- **Node.js**: Ensure you have Node.js installed.
40+
- **Packages**: Install the following packages:
41+
42+
```bash
43+
npm install @mastra/core @mastra/mcp @ai-sdk/openai
44+
```
45+
46+
### Building the TikTok profile search and analysis agent
47+
48+
First import all required packages:
49+
50+
```typescript
51+
import { Agent } from '@mastra/core/agent';
52+
import { MastraMCPClient } from '@mastra/mcp';
53+
import { openai } from '@ai-sdk/openai';
54+
```
55+
56+
Next, set the environment variables for the Apify API token and OpenAI API key:
57+
58+
```typescript
59+
process.env.APIFY_TOKEN = "your-apify-token";
60+
process.env.OPENAI_API_KEY = "your-openai-api-key";
61+
```
62+
63+
Instantiate the Mastra MCP client:
64+
65+
```typescript
66+
const mcpClient = new MastraMCPClient({
67+
name: 'apify-client',
68+
server: {
69+
url: new URL('https://actors-mcp-server.apify.actor/sse'),
70+
requestInit: {
71+
headers: { Authorization: `Bearer ${process.env.APIFY_TOKEN}` }
72+
},
73+
// The EventSource package augments EventSourceInit with a "fetch" parameter.
74+
// You can use this to set additional headers on the outgoing request.
75+
// Based on this example: https://github.com/modelcontextprotocol/typescript-sdk/issues/118
76+
eventSourceInit: {
77+
async fetch(input: Request | URL | string, init?: RequestInit) {
78+
const headers = new Headers(init?.headers || {});
79+
headers.set('authorization', `Bearer ${process.env.APIFY_TOKEN}`);
80+
return fetch(input, { ...init, headers });
81+
}
82+
}
83+
}
84+
});
85+
```
86+
87+
Connect to the MCP server and fetch the tools:
88+
89+
```typescript
90+
console.log('Connecting to Mastra MCP server...');
91+
await mcpClient.connect();
92+
console.log('Fetching tools...');
93+
const tools = await mcpClient.tools();
94+
```
95+
96+
Instantiate the agent with the OpenAI model:
97+
98+
```typescript
99+
const agent = new Agent({
100+
name: 'TikTokAnalyzer',
101+
instructions: 'You’re a social media data extractor. Find TikTok URLs and analyze profiles with precision.',
102+
model: openai('gpt-4o-mini')
103+
});
104+
```
105+
106+
Generate a response using the agent and the Apify tools:
107+
108+
```typescript
109+
const prompt = 'Search the web for the OpenAI TikTok profile URL, then extract and summarize its data.';
110+
console.log(`Generating response for prompt: ${prompt}`);
111+
const response = await agent.generate(prompt, {
112+
toolsets: { apify: tools }
113+
});
114+
```
115+
116+
Print the response and disconnect from the MCP server:
117+
118+
```typescript
119+
console.log(response.text);
120+
await mcpClient.disconnect();
121+
```
122+
123+
Before running the agent we need to start the Apify MCP Server by sending a request:
124+
125+
```bash
126+
curl https://actors-mcp-server.apify.actor/?token=YOUR_APIFY_TOKEN&actors=apify/rag-web-browser,clockworks/free-tiktok-scraper
127+
```
128+
129+
Replace `YOUR_APIFY_TOKEN` with your Apify API token. You can also open the URL in a browser to start the server.
130+
131+
:::note Use any Apify Actor
132+
133+
Since it uses the MCP Server, swap in any Apify Actor from the [Apify Store](https://apify.com/store) by updating the startup request’s `actors` parameter.
134+
135+
:::
136+
137+
Run the agent:
138+
139+
```bash
140+
npx tsx mastra-agent.ts
141+
```
142+
143+
:::note Execution Time
144+
145+
Web searches and TikTok scraping might take a minute—depends on the Actors and network.
146+
147+
:::
148+
149+
You will see the agent’s output in the console, showing the results of the search and analysis.
150+
151+
```text
152+
Connecting to Mastra MCP server...
153+
Fetching tools...
154+
Generating response for prompt: Search the web for the OpenAI TikTok profile URL, then extr
155+
act and summarize its data.
156+
### OpenAI TikTok Profile Summary
157+
- **Profile URL**: [OpenAI on TikTok](https://www.tiktok.com/@openai?lang=en) - **Followers**: 608,100
158+
- **Likes**: 3.4 million
159+
- **Videos Posted**: 156
160+
- **Bio**: "low key research previews"
161+
...
162+
```
163+
164+
If you want to test the whole example, create a new file, `mastra-agent.ts`, and copy the full code into it:
165+
166+
```typescript
167+
import { Agent } from '@mastra/core/agent';
168+
import { MastraMCPClient } from '@mastra/mcp';
169+
import { openai } from '@ai-sdk/openai';
170+
171+
process.env.APIFY_TOKEN = "your-apify-token";
172+
process.env.OPENAI_API_KEY = "your-openai-api-key";
173+
174+
const mcpClient = new MastraMCPClient({
175+
name: 'apify-client',
176+
server: {
177+
url: new URL('https://actors-mcp-server.apify.actor/sse'),
178+
requestInit: {
179+
headers: { Authorization: `Bearer ${process.env.APIFY_TOKEN}` }
180+
},
181+
// The EventSource package augments EventSourceInit with a "fetch" parameter.
182+
// You can use this to set additional headers on the outgoing request.
183+
// Based on this example: https://github.com/modelcontextprotocol/typescript-sdk/issues/118
184+
eventSourceInit: {
185+
async fetch(input: Request | URL | string, init?: RequestInit) {
186+
const headers = new Headers(init?.headers || {});
187+
headers.set('authorization', `Bearer ${process.env.APIFY_TOKEN}`);
188+
return fetch(input, { ...init, headers });
189+
}
190+
}
191+
}
192+
});
193+
194+
console.log('Connecting to Mastra MCP server...');
195+
await mcpClient.connect();
196+
console.log('Fetching tools...');
197+
const tools = await mcpClient.tools();
198+
199+
const agent = new Agent({
200+
name: 'TikTokAnalyzer',
201+
instructions: 'You’re a data extractor. Find TikTok URLs and analyze profiles with precision.',
202+
model: openai('gpt-4o-mini')
203+
});
204+
205+
const prompt = 'Search the web for the OpenAI TikTok profile URL, then extract and summarize its data.';
206+
console.log(`Generating response for prompt: ${prompt}`);
207+
const response = await agent.generate(prompt, {
208+
toolsets: { apify: tools }
209+
});
210+
211+
console.log(response.text);
212+
await mcpClient.disconnect();
213+
```
214+
215+
## Resources
216+
217+
- [Apify Actors](https://docs.apify.com/platform/actors)
218+
- [Mastra Documentation](https://mastra.ai/docs)
219+
- [Apify MCP Server](https://apify.com/apify/actors-mcp-server)
220+
- [Apify Store](https://apify.com/store)
221+
- [What are AI Agents?](https://blog.apify.com/what-are-ai-agents/)
222+
- [How to Build an AI Agent](https://blog.apify.com/how-to-build-an-ai-agent/)

0 commit comments

Comments
 (0)