Vercel AI SDK

Use Openhandle operations as tools inside an agent built with the Vercel AI SDK.

Two ways to do it. Connect the MCP server and let the SDK turn every operation into a tool, or call the REST API from a hand-written tool when you want full control.

Option A: MCP client

The AI SDK can connect to an MCP server over Streamable HTTP. Install the client in your agent application:

pnpm add ai @ai-sdk/mcp

Pass your configured model and a prompt to this function. The model must support tool calling. Keep this code on the server.

import { createMCPClient } from '@ai-sdk/mcp';
import { generateText, stepCountIs, type LanguageModel } from 'ai';

export async function answerSocialQuestion(model: LanguageModel, prompt: string) {
  const apiKey = process.env.OPENHANDLE_TEST_KEY;
  if (!apiKey) throw new Error('Set OPENHANDLE_TEST_KEY on the server.');

  const openhandle = await createMCPClient({
    transport: {
      type: 'http',
      url: 'https://api.openhandle.dev/mcp',
      headers: { Authorization: `Bearer ${apiKey}` },
    },
  });

  try {
    const result = await generateText({
      model,
      tools: await openhandle.tools(),
      stopWhen: stepCountIs(5),
      prompt,
    });
    return result.text;
  } finally {
    await openhandle.close();
  }
}

The client closes after generation, including when a request fails. For streaming, keep the client open until the stream finishes. See the AI SDK MCP guide for streaming cleanup.

Option B: one REST tool

Install the tool dependencies:

pnpm add ai zod

import { tool } from 'ai';
import { z } from 'zod';

export const instagramProfile = tool({
  description: 'Public Instagram profile by handle',
  inputSchema: z.object({ handle: z.string() }),
  execute: async ({ handle }) => {
    const response = await fetch(`https://api.openhandle.dev/v1/instagram/profiles/@${handle}`, {
      headers: { Authorization: `Bearer ${process.env.OPENHANDLE_TEST_KEY}` },
    });
    return response.json();
  },
});

Every answer has the same envelope: platform, resource, capturedAt, source, and data. Missing metrics are null, so tell the model that null means unknown, not zero.

Notes

Use a Test key while you build. It is free and runs the full pipeline.
The OpenAPI spec has every operation and schema if you want to generate tools from it.

Vercel AI SDK

Option A: MCP client

Option B: one REST tool

Notes

On this page