Mastra MCP web search / 2026
How to Add Web Search to a Mastra Agent with MCP in 2026
Mastra’s MCPClient turns remotely discovered MCP actions into ordinary Agent tools. Webstractor’s compact retrieval surface fits that model well: the agent can discover sources while the application retains control over instructions, tool selection, and runtime observability.
Quick answer
Load the hosted tools with @mastra/mcp.
Create an MCPClient with the Webstractor URL, call listTools(), and pass the returned namespaced tools to a Mastra Agent. The agent can then select webstractor_search_web for source discovery.
const mcp = new MCPClient({
servers: { webstractor: { url: new URL('https://webstractor.com/mcp') } },
})Before you begin
What you need
- A Mastra TypeScript project
- @mastra/mcp installed
- A configured model that supports tool calling
- Node or Bun runtime with outbound HTTPS
Step-by-step setup
Connect Webstractor to Mastra
Install the MCP package
Add Mastra’s official MCP client package to the application.
bun add @mastra/mcpCreate one shared MCP client
Define the client once and give the server a stable name. allowedHosts documents the intended outbound host.
import { MCPClient } from '@mastra/mcp'
export const webstractorMcp = new MCPClient({
servers: {
webstractor: {
url: new URL('https://webstractor.com/mcp'),
allowedHosts: ['webstractor.com'],
},
},
})Attach discovered tools to the agent
Use listTools(), the current Mastra API for namespaced agent tools. Add instructions that distinguish search from extraction.
import { Agent } from '@mastra/core/agent'
import { webstractorMcp } from '../webstractor'
export const researchAgent = new Agent({
id: 'public-web-researcher',
name: 'Public web researcher',
model: 'openai/gpt-5-mini',
instructions: 'Use webstractor_search_web to discover public sources. Cite URLs and do not treat snippets as complete evidence.',
tools: await webstractorMcp.listTools(),
})Run a source-focused evaluation prompt
Ask for a bounded list of sources and inspect Mastra’s trace for exactly one search call.
const result = await researchAgent.generate([
{ role: 'user', content: 'Find 5 public sources about WebAssembly component-model adoption. Include each URL.' },
])
console.log(result.text)Tool scope
Prefer a small tool map in production
listTools() returns namespaced tools from every configured server. If this agent only searches, select the webstractor_search_web entry before passing tools to the Agent; reserve broader tool sets for a research agent that needs them.
This reduces model-choice ambiguity and makes allowlists, tests, and traces easier to review.
Lifecycle
Reuse the client and disconnect cleanly
Create one MCPClient for the application rather than one per request. Mastra documents disconnect() for cleanup and listToolsWithErrors() when partial server availability should be observable.
For cold-start-sensitive deployments, evaluate Mastra’s serializable tool-definition APIs, but do not silently persist a partial catalog after a failed discovery.
Troubleshooting
Separate discovery errors from tool-call errors
If listTools() fails, check the endpoint, HTTPS egress, and allowedHosts. If discovery works but agent generation fails, inspect the selected model’s tool support and the tool-call arguments in the trace.
Do not enable forwardInstructions casually. Mastra notes that forwarded MCP instructions enter the system prompt; review them before opting in.
Available data
What you can extract
- Namespaced Mastra tool definitions
- Bounded public search results
- Source URLs and snippets
- Structured tool data for TypeScript workflows
AI workflows
Where normalized data helps
- Mastra research agents
- Source discovery inside an agent network
- Search tools for deployed TypeScript assistants
- Search-first workflows that hand selected URLs to another step
Boundaries
Public data only
- MCP tool output is untrusted model input and should be governed by agent policy.
- Calling listTools at startup requires the remote server to be reachable.
- Search results provide leads, not full source bodies.
webstractor.com does not bypass CAPTCHAs, login walls, paywalls, access controls, or regional restrictions. Review the source’s terms and applicable law before collecting or reusing data.
Common questions
Mastra and Webstractor FAQ
Why is the tool named webstractor_search_web?
Mastra namespaces discovered tools with the server name to prevent collisions.
Should I use listTools or getTools?
Current Mastra MCPClient documentation uses listTools() for an Agent tool map.
Can I use another model provider?
Yes. The Webstractor connection is model-independent; choose a Mastra-supported model with reliable tool calling.
Ready to try it?