Skip to the page

Mastra

Mastra's @mastra/tavily tools work with SpecStream when you change their address. Pass your SpecStream key and https://api.specstream.ai/tavily as the base URL, and a Mastra agent's search and extract tools answer from the live web.

SpecStream for Mastra, Agent frameworks & builders

What you need

  • A Mastra project with @mastra/core and a model that supports tool calls.
  • A SpecStream API key. New accounts start with $10 of credit, no card. Get your key on the Search API screen of your workspace.
  1. 1. Install the tools

    Install Mastra's Tavily integration and its client. Keep your SpecStream key in an environment variable:

    Terminal
    npm install @mastra/tavily @tavily/core zod
    export SPECSTREAM_API_KEY="YOUR_SPECSTREAM_API_KEY"
  2. 2. Point them at SpecStream

    Every factory in @mastra/tavily takes the Tavily client's options. Set apiKey to your SpecStream key and apiBaseURL to SpecStream's Tavily address. Create the search and extract tools one by one: SpecStream answers Tavily's search, extract and map requests, and not its crawl request, so leave createTavilyTools() and its crawl tool out.

    src/mastra/agents/researcher.ts
    import { Agent } from "@mastra/core/agent";
    import { createTavilySearchTool, createTavilyExtractTool } from "@mastra/tavily";
    const specstream = {
    apiKey: process.env.SPECSTREAM_API_KEY,
    apiBaseURL: "https://api.specstream.ai/tavily",
    };
    export const researcher = new Agent({
    id: "researcher",
    name: "Researcher",
    model: "openai/gpt-4o-mini",
    instructions: "Search the live web, read the pages you rely on, and name each page you used.",
    tools: {
    search: createTavilySearchTool(specstream),
    extract: createTavilyExtractTool(specstream),
    },
    });
  3. 3. Ask

    Run the agent with a question about something recent. It calls tavily-search, then tavily-extract on the pages it needs:

    src/index.ts
    import { researcher } from "./mastra/agents/researcher";
    const result = await researcher.generate(
    "What changed in the latest Mastra release? Read the changelog.",
    );
    console.log(result.text);

What SpecStream answers

tavily-search sends POST https://api.specstream.ai/tavily/search with your key as a Bearer token. SpecStream answers in Tavily's shape, results[].title, url and content, so the tool's output is unchanged. tavily-extract sends POST /tavily/extract with up to 20 URLs and gets each page's raw_content back.

We ran the search tool of @mastra/tavily 1.1.3 against this address on November 12, 2026.

Or use SpecStream's MCP server

For Deep Search, which reads a request in plain words, prices it, and returns rows with a source on every value, connect Mastra's MCPClient to SpecStream's MCP server. listTools() returns search_web, read_pages and the Deep Search tools:

src/mastra/mcp.ts
import { MCPClient } from "@mastra/mcp";
export const mcp = new MCPClient({
servers: {
specstream: {
url: new URL("https://api.specstream.ai/mcp"),
requestInit: {
headers: { Authorization: `Bearer ${process.env.SPECSTREAM_API_KEY}` },
},
},
},
});
// In the agent: tools: await mcp.listTools()

Errors

  • 401: the key is missing or wrong. apiKey takes your SpecStream key, sent as a Bearer token.
  • 429 with Retry-After: search is busy, or the key used its calls for the minute. Wait that many seconds and send it again.

Cost

Each search through the Tavily address is one fast search at $1 per 1,000 searches of up to 10 results. When the agent sets includeAnswer, the search runs the default search at $5 per 1,000. Each page the extract tool reads is $0.80 per 1,000 pages. They come out of your balance up to the key's spending limit, with no quote and no approval. Balance, quotes, and billing has the details.

Remove

Take apiKey and apiBaseURL out of the tool options, or remove the tools from the agent. To stop the key working everywhere, revoke it under API keys in Agents & API. Results already delivered stay in your workspace. Questions go to [email protected].

More

SpecStream for Mastra covers what it does in Mastra on one page. Every other tool has its guide in Connect your tools. You see the most a request can cost before it starts, and the matches are paid from your balance. Billing has the details. For help, email [email protected].