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

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.
A SpecStream API key with a spending limit, which step 1 creates.

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
export SPECSTREAM_API_KEY="YOUR_SPECSTREAM_API_KEY"

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
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. 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
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. 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
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 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 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. Questions go to [email protected].

SpecStream for VoltAgent covers what it does in VoltAgent 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].