@usestring/ai-sdk

String Web Access tools for the Vercel AI SDK.

Search the web, fetch any URL or send it a request, and map a site's URLs — all returned as clean, LLM-ready Markdown.

AI SDK guide →

Install

npm install @usestring/ai-sdk ai

ai and zod are peer dependencies, so a project already on the AI SDK has them.

API key

Get a key from your String settings and set it:

export STRING_API_KEY=...

Or pass { apiKey } to any tool.

Quick start

import { generateText, isStepCount } from 'ai';
import { stringFetch, stringSearch } from '@usestring/ai-sdk';

const { text } = await generateText({
  model: 'openai/gpt-5-mini',
  prompt:
    'Find the latest Node.js LTS release, read its release notes, and list the three most important changes.',
  tools: {
    search: stringSearch(),
    fetch: stringFetch(),
  },
  stopWhen: isStepCount(5),
});

console.log(text);

Model strings such as 'openai/gpt-5-mini' go through AI Gateway and need AI_GATEWAY_API_KEY. To call a provider directly, install its package, such as @ai-sdk/openai, and pass openai('gpt-5-mini') instead.

Tools

Each tool is a factory that returns an AI SDK tool. Every call opens its own connection to the hosted String MCP server at https://mcp.usestring.ai/v1/mcp, so there is nothing to close.

stringSearch

Searches the web and returns ranked results with their titles, links and snippets. It runs the server's web_access_search tool.

tools: { search: stringSearch({ searchCount: 30 }) }

Options, set in code:

• searchCount?: number — organic results to collect, 1 to 300. Each page of about ten results is billed as one search. Defaults to one page.

Inputs, chosen by the model: query, and optionally country, language and location.

stringFetch

Fetches a URL and returns the page as clean Markdown, its verbatim body, or a JSON envelope with the status code, headers and body. It runs web_access_fetch.

tools: { fetch: stringFetch({ countryCode: 'DE' }) }

Options, set in code:

• countryCode?: string — two-letter ISO 3166-1 country code the page is fetched from.
• solveCaptcha?: boolean — set false to fail fast on a challenge page. Defaults to true.

Inputs, chosen by the model: url, and optionally format (markdown, raw or json) and executeJS.

stringRequest

Sends a POST, PUT or PATCH with a body and returns the response, for GraphQL queries and JSON APIs that do not accept GET. It runs web_access_request. The request reaches the destination, so give this tool only to an agent that should submit data.

tools: { request: stringRequest() }

Options, set in code: countryCode and solveCaptcha, as for stringFetch.

Inputs, chosen by the model: url, method, and optionally body and format.

stringSitemap

Lists the URLs on a website through an asynchronous crawl job. It runs web_access_sitemap, one tool for the whole job: submit returns a cost quote without crawling, approve starts the billed crawl, status and results read it, cancel stops it and list shows recent jobs.

tools: { sitemap: stringSitemap({ budgetUsd: 1 }) }

Options, set in code:

• budgetUsd?: number — spend ceiling for each crawl this tool submits. Defaults to the approved quote.

Inputs, chosen by the model: action, and per action url, jobId, maxPages, maxDepth, pathPrefix, useSitemap, limit and offset.

Choosing tools

createStringTools returns the tools keyed by their server names. Search and fetch are on by default; request and sitemap are off until you turn them on. Pass false to leave a tool out, or an object to configure it.

import { createStringTools } from '@usestring/ai-sdk';

const tools = createStringTools({
  search: { searchCount: 20 },
  sitemap: { budgetUsd: 1 },
});
// { web_access_search, web_access_fetch, web_access_sitemap }

Every server tool

withStringTools hands your callback every tool the server lists, discovered at connect time, and closes the connection when the callback settles, whether it resolves or throws. A tool added to the server reaches your agent without a package upgrade.

import { generateText, isStepCount } from 'ai';
import { withStringTools } from '@usestring/ai-sdk';

const { text } = await withStringTools({}, ({ tools }) =>
  generateText({
    model: 'openai/gpt-5-mini',
    tools,
    stopWhen: isStepCount(5),
    prompt: 'Find the latest Node.js LTS release and list the three most important changes.',
  }),
);

For an agent that reuses one connection across turns, open the client yourself and own its lifetime:

import { createStringMCPClient } from '@usestring/ai-sdk';

const client = await createStringMCPClient();
const tools = await client.tools();

// ... many generations ...

await client.close();

Shared options

Every factory, createStringTools, withStringTools and createStringMCPClient accept these:

Option	Default	Description
apiKey	process.env.STRING_API_KEY	Your String API key.
url	https://mcp.usestring.ai/v1/mcp	Point this at your own server if you self-host.
headers	—	Extra HTTP headers sent with every request. Authorization is always set from apiKey.
clientName	@usestring/ai-sdk	Client name advertised during initialization.

Development

npm ci
npm test        # unit tests, no network
npm run build

npm run test:live connects to the hosted server with STRING_API_KEY, read from your environment or from a .env file (copy .env.example), and checks that every tool here is listed and sends only arguments the server accepts. It lists the tools and calls none of them.

npm run example runs examples/generate-text.ts, the quick start above, end to end. It also needs AI_GATEWAY_API_KEY, and it makes real, billed tool calls.

Links

• AI SDK guide: https://portal.usestring.ai/docs/guides/ai-sdk
• MCP server: https://portal.usestring.ai/docs/mcp/overview
• REST API: https://portal.usestring.ai/docs/api-reference/overview

License

MIT