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

# VoltAgent

Add SpecStream to a VoltAgent agent through MCPConfiguration, and the agent searches the live web, reads pages and asks for structured records, all with one API key.

[SpecStream for VoltAgentAgent frameworks & builders](https://specstream.ai/integrations/voltagent.md)

## What you need

-   A VoltAgent project on @voltagent/core, with a model that supports tool calls.
-   A SpecStream account. New accounts get $10 of credit, no card. [Create one](https://specstream.ai/signup?utm_source=voltagent).
-   A SpecStream API key with a spending limit, which step 1 creates.

1.  1

    ## 1. Create an API key

    In your SpecStream workspace, open **Agents & API**, choose **API keys**, then **Create API key**. Turn on **Authorize paid work**: a key without it can't search or read pages. Set a **Total spending limit** above $0, because that limit is what caps the agent's spending on searches and page reads.

    Copy the key when it's shown. It isn't shown again. Keep it in an environment variable where the agent runs:

    Terminal

    ```bash
    export SPECSTREAM_API_KEY="YOUR_SPECSTREAM_API_KEY"
    ```

2.  2

    ## 2. Add SpecStream to MCPConfiguration

    Add a `specstream` entry under `servers`. SpecStream's server speaks Streamable HTTP, so use `type: "streamable-http"`. The `http` type works too, but it falls back to SSE when a connection fails, and SpecStream has no SSE route. The key goes in `requestInit.headers` as a Bearer token. VoltAgent's default `timeout` is 30,000 ms. Set your own when your calls need longer.

    src/index.ts

    ```typescript
    import { Agent, MCPConfiguration } from "@voltagent/core";
    
    const mcpConfig = new MCPConfiguration({
      servers: {
        specstream: {
          type: "streamable-http",
          url: "https://api.specstream.ai/mcp",
          requestInit: {
            headers: { Authorization: `Bearer ${process.env.SPECSTREAM_API_KEY}` },
          },
        },
      },
    });
    ```

3.  3

    ## 3. Give the tools to the agent

    `getTools()` returns every SpecStream tool as a VoltAgent tool. VoltAgent puts the server name in front of each tool name, so `search_web` reaches the agent as `specstream_search_web` and `read_pages` as `specstream_read_pages`.

    To give the agent only web search and page reading, keep those two names:

    src/index.ts

    ```typescript
    const webTools = (await mcpConfig.getTools()).filter((tool) =>
      ["specstream_search_web", "specstream_read_pages"].includes(tool.name),
    );
    
    const agent = new Agent({
      name: "Researcher",
      instructions: "Search the live web with SpecStream, read the pages you rely on, and name each page you used.",
      model: "openai/gpt-4o-mini",
      tools: webTools,
    });
    ```

4.  4

    ## 4. Ask

    Run the agent with a question about something current. It calls `specstream_search_web`, then `specstream_read_pages` on the results it needs. Call `disconnect()` when the process is done with the tools.

    src/index.ts

    ```typescript
    const result = await agent.generateText(
      "What changed in the latest VoltAgent release? Read the release notes.",
      { userId: "user123" },
    );
    console.log(result.text);
    
    await mcpConfig.disconnect();
    ```

## What each tool does

The SpecStream server gives the agent three kinds of work. Pass all of `getTools()` to use them all, or filter as in step 3.

| Tool in VoltAgent | What it does | Cost |
| --- | --- | --- |
| `specstream_search_web` | Searches the live web with `{"q": "<the question>"}` and returns up to 10 results. | $5 per 1,000 searches |
| `specstream_read_pages` | Returns the main text of 1 to 20 pages or documents (PDF, Word, Excel), read live, with `{"urls": [...]}`. | $0.80 per 1,000 pages. A page with no text is not charged. |
| `specstream_compile`, `specstream_quote_capacity_work`, `specstream_authorize_capacity_work` | Deep Search: reads a request in plain words, prices it, and starts it after a maximum is approved. Rows come back with `specstream_list_find_rows`. | 5¢, 15¢ or $1 a delivered row, plus 5¢ for a person's email and 15¢ for a phone |

## Deep Search in an agent

`specstream_compile` reads the request and returns the conditions and the fields to bring back. `specstream_quote_capacity_work` prices it, and the quote lasts 30 minutes. `specstream_authorize_capacity_work` starts the work only with the approved maximum in `confirm_max_cents`. Reading and pricing cost nothing.

Approve the maximum in your own code, or ask the person the agent works for. To keep paid Deep Search runs out of an agent, leave `specstream_authorize_capacity_work` out of its tools. The [agent guide](https://specstream.ai/docs/mcp.md) covers every tool.

## Without MCP: a VoltAgent tool on the Search API

The Search API answers the same search over plain HTTP. Wrap it in `createTool` when you'd rather not run an MCP client:

## Errors

-   `403`: the key has no **Authorize paid work**, or the call would go over the key's spending limit.
-   `402`: the balance is empty, or the call would go over the account's monthly spending limit.
-   `503` with `Retry-After`: wait that many seconds and send it again. Nothing is charged.

## Cost

Connecting SpecStream to VoltAgent is free. A search is $5 per 1,000 searches of up to 10 results, and a page read is $0.80 per 1,000 pages. Neither needs a quote or an approval, so they come out of your balance up to the key's spending limit. Deep Search rows cost 5¢, 15¢ or $1, and a run can't cost more than the maximum approved. New accounts start with $10 of credit, no card. [Balance, quotes, and billing](https://specstream.ai/docs/billing.md) has the details.

## Remove

Take the `specstream` entry out of `MCPConfiguration`. To stop the key working everywhere, revoke it under **API keys** in **Agents & API**. Results already delivered stay in your workspace. Other frameworks are in [agent frameworks](https://specstream.ai/docs/frameworks.md). Questions go to [support@specstream.ai](mailto:support@specstream.ai).

## More

[SpecStream for VoltAgent](https://specstream.ai/integrations/voltagent.md) covers what it does in VoltAgent 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).