> SpecStream is the live web data engine for teams and agents. This is the Markdown copy of https://specstream.ai/docs/integrations/mastra. Every page, with what SpecStream does and costs: https://specstream.ai/llms.txt

# 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](https://specstream.ai/integrations/mastra.md)

## 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](https://specstream.ai/workspace/search?route=tavily&utm_source=mastra&utm_medium=howto) on the Search API screen of your workspace.

1.  1

    ## 1. Install the tools

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

    Terminal

    ```bash
    npm install @mastra/tavily @tavily/core zod
    export SPECSTREAM_API_KEY="YOUR_SPECSTREAM_API_KEY"
    ```

2.  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

    ```typescript
    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

    ## 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

    ```typescript
    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

```typescript
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](https://specstream.ai/docs/billing.md) 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 [support@specstream.ai](mailto:support@specstream.ai).

## More

[SpecStream for Mastra](https://specstream.ai/integrations/mastra.md) covers what it does in Mastra on one page. Every other tool has its guide in [Connect your tools](https://specstream.ai/docs/integrations.md). You see the most a request can cost before it starts, and the matches are paid from your balance. [Billing](https://specstream.ai/docs/billing.md) has the details. For help, email [support@specstream.ai](mailto:support@specstream.ai).
