# Vercel AI SDK {#vercel-ai-sdk}


`@nitrosend/ai-sdk` exposes Nitrosend's MCP tool surface — drafting campaigns,
sending tests, managing contacts, building flows, and reviewing delivery — to applications
built on the [Vercel AI SDK](https://ai-sdk.dev). It is a typed wrapper
over the Nitrosend remote MCP server and is **not** a model package.


## Install {#install}


```bash
npm install @nitrosend/ai-sdk ai @ai-sdk/mcp zod
```

The examples below also use `@ai-sdk/openai` for the model. Substitute
your preferred AI SDK model package (`@ai-sdk/anthropic`,
`@ai-sdk/google`, etc.):

```bash
npm install @ai-sdk/openai
```


## Authenticate {#authenticate}


Get a key from **Settings → API Keys** ([app.nitrosend.com/my/settings/api-keys](https://app.nitrosend.com/my/settings/api-keys)) and export it. The package reads
`NITROSEND_API_KEY` automatically, or you can pass `apiKey` explicitly.

```bash
export NITROSEND_API_KEY="nskey_live_<your-api-key>"
```


## Quickstart — generateText {#quickstart--generatetext}


`stopWhen: isStepCount(N)` is required for tool-calling workflows: AI SDK
defaults to a single step, so without it the call stops as soon as the
model invokes a Nitrosend tool and you never see the final summary text.

```ts
import { generateText, isStepCount } from 'ai';
import { openai } from '@ai-sdk/openai';
import { withNitrosendTools } from '@nitrosend/ai-sdk';

const result = await withNitrosendTools({}, async ({ tools }) => {
  return generateText({
    model: openai('gpt-4o'),
    tools,
    stopWhen: isStepCount(5),
    prompt: 'Draft a welcome campaign for the Newsletter list.',
  });
});
```


## Streaming — streamText {#streaming--streamtext}


```ts
import { streamText, isStepCount } from 'ai';
import { openai } from '@ai-sdk/openai';
import { withNitrosendTools } from '@nitrosend/ai-sdk';

await withNitrosendTools({}, async ({ tools }) => {
  const stream = streamText({
    model: openai('gpt-4o'),
    tools,
    stopWhen: isStepCount(5),
    prompt: 'Add founder@acme.com to the "Power users" list and confirm.',
  });

  for await (const part of stream.textStream) {
    process.stdout.write(part);
  }

  await stream.consumeStream();
});
```

`withNitrosendTools` opens the MCP transport, hands you the toolset, and
closes the transport in a `finally` block when your callback resolves or
throws — including when `streamText` is awaited inside.


## Lifecycle and subsets {#lifecycle-and-subsets}


For longer-lived processes, hold the client yourself:

```ts
import { nitrosend } from '@nitrosend/ai-sdk';

const { tools, client, close } = await nitrosend();
try {
  // …pass `tools` to generateText/streamText, or use `client` directly…
} finally {
  await close();
}
```

Filter the toolset to only what your agent should reach for — types narrow
to match. Use `withNitrosendTools` so the transport closes after use:

```ts
import { withNitrosendTools } from '@nitrosend/ai-sdk';

await withNitrosendTools(
  { tools: ['nitro_get_status', 'nitro_compose_campaign'] },
  async ({ tools }) => {
    // tools is typed to exactly { nitro_get_status, nitro_compose_campaign }
  },
);
```


## Errors {#errors}


The wrapper does not retry. All failures throw `NitrosendAISDKError` with
a stable `.code` and the original error preserved on `.cause`:

- `AUTH_MISSING` — no credential was found in options or env.
- `AUTH_INVALID_PREFIX` — `apiKey` did not start with `nskey_live_` / `nskey_test_`.
- `CLIENT_INIT_FAILED` — MCP transport could not connect (check URL, network, key).
- `TOOLS_LIST_FAILED` — server rejected the tools list call.


## Related {#related}


- [REST API](https://docs.nitrosend.com/integrations/rest-api.md) — Nitrosend HTTP API used by `@nitrosend/sdk`.
- [MCP overview](https://docs.nitrosend.com/integrations/overview.md) — connecting Claude Desktop / Cursor / IDEs via
  the `@nitrosend/mcp` stdio bridge.
- [Tools Registry submission](https://ai-sdk.dev/tools-registry) — public
  AI SDK tool directory; this package targets that listing.

For one-click installation, account-scoped credentials, and marketplace billing,
see the [Vercel Marketplace integration](https://docs.nitrosend.com/integrations/vercel-marketplace.md), which is awaiting Vercel approval.
