gem-hunter
Language: TypeScript
Vercel AI SDK tools for Nitrosend — typed Zod schemas over the remote Nitrosend MCP server
Vercel AI SDK tools for Nitrosend — the multi-channel
marketing platform. Drops Nitrosend's 23 MCP tools (draft campaigns, manage
contacts, build flows, send tests, …) into generateText, streamText, and
agent loops.
This package is a thin, typed wrapper over Nitrosend's remote MCP server. It
ships the Nitrosend tool surface for AI SDK developers — it is not a
language model implementation, and it does not replace @ai-sdk/openai,
@ai-sdk/anthropic, or any other model package.
All plans, including free plans, have full access to Nitrosend MCP/API/CLI. MCP and AI SDK usage are not restricted to paid plans; plan limits apply to usage volume and paid add-ons.
npm install @nitrosend/ai-sdk ai @ai-sdk/mcp zod
The examples below also use @ai-sdk/openai to pick a model. Replace it
with whichever AI SDK model package you use (@ai-sdk/anthropic,
@ai-sdk/google, etc.):
npm install @ai-sdk/openai
Set one of:
| Variable | Purpose |
|---|---|
NITROSEND_API_KEY |
Nitrosend API key (nskey_live_… / nskey_test_…). |
NITROSEND_BEARER_TOKEN |
Opaque bearer issued by your own auth flow. |
NITROSEND_MCP_URL |
Override the MCP endpoint (defaults to prod). |
Get an API key from Brand → API Keys in the Nitrosend dashboard.
generateText (one-shot completion). stopWhen: isStepCount(N) lets the
model take a follow-up step after a tool call so the final summary text
gets back to you — without it, AI SDK stops after the first tool result:
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 from our team.', }); }); console.log(result.text);
streamText (token-stream UI):
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: 'Find the founder@acme.com contact and add them to the "Power users" list.', }); for await (const part of stream.textStream) { process.stdout.write(part); } await stream.consumeStream(); });
withNitrosendTools reads NITROSEND_API_KEY from the environment, opens
the MCP transport, runs your callback, and closes the transport in a
finally block — including when streamText is awaited inside the
callback (the close runs after the stream is fully consumed).
If you need the raw client (e.g. inside a long-running server), call
nitrosend() directly and close it yourself:
import { nitrosend } from '@nitrosend/ai-sdk'; const { tools, client, close } = await nitrosend({ apiKey: process.env.NITROSEND_API_KEY }); try { // …use tools / client.listResources() / client.experimental_listPrompts() … } finally { await close(); }
Restrict the toolset to specific tools — this filters at the MCP layer and
narrows the TypeScript types. Always use withNitrosendTools (or your
own try/finally) so the transport closes:
import { withNitrosendTools } from '@nitrosend/ai-sdk'; await withNitrosendTools( { tools: ['nitro_get_status', 'nitro_compose_campaign'] }, async ({ tools }) => { // tools is typed as { nitro_get_status: …; nitro_compose_campaign: … } }, );
If you must hold the client outside a callback, retain the close handle
and run it in a finally yourself:
import { createNitrosendMCPClient, pickNitrosendToolSchemas } from '@nitrosend/ai-sdk'; const client = await createNitrosendMCPClient(); try { const tools = await client.tools({ schemas: pickNitrosendToolSchemas('nitro_compose_flow', 'nitro_send_test_message'), }); // …use tools… } finally { await client.close(); }
All wrapper failures throw NitrosendAISDKError with a stable .code
(AUTH_MISSING, AUTH_INVALID_PREFIX, CLIENT_INIT_FAILED,
TOOLS_LIST_FAILED) and the original cause preserved. The wrapper does
not retry — mutating tool calls (sends, imports, deletes) must remain
caller-driven. Network errors and 5xx responses surface to your code so
your application can decide what to do.
| Use case | Reach for |
|---|---|
| AI agents calling Nitrosend tools | @nitrosend/ai-sdk (this package) |
| Plain HTTP from any language | @nitrosend/sdk |
| Claude Desktop / Cursor / IDE MCP clients | @nitrosend/mcp |
@nitrosend/sdk is the typed REST client for app code. @nitrosend/mcp is
the stdio MCP bridge consumed by IDE clients. This package targets
programmatic AI SDK usage and does not duplicate either. All three speak to
the same Nitrosend backend.