OpenAI SDK (Agents)

Overview

Integrate Leadovaro with the OpenAI Agents SDK using hostedMcpTool() — the simplest way to use Leadovaro with OpenAI. No manual tool looping or schema conversion required.

note

For the older manual function calling approach, see OpenAI SDK (Node.js).

Prerequisites

• Leadovaro account at app.leadovaro.com with at least one MCP server connected
• OpenAI API key from platform.openai.com

Installation

npm install @openai/agents

The openai package is bundled as a dependency — no need to install it separately.

Authentication

For autonomous agents and server-side scripts — use a Leadovaro token directly.

Generate a Leadovaro Token

1. Log in to app.leadovaro.com
2. Click your account name in the bottom left
3. Go to Install → MCP URL
4. Click Generate Token and copy it immediately — it won't be shown again

warning

Never commit your token to source control. Store it in environment variables or a secrets manager. Tokens expire after 30 days.

Set Environment Variables

LEADOVARO_TOKEN=your-leadovaro-token-here
LEADOVARO_URL=/_sites/app.leadovaro.com/hub/mcp

For production agents, lock to a specific toolkit by appending a profile parameter:

LEADOVARO_URL=/_sites/app.leadovaro.com/hub/mcp?profile=your-toolkit-alias

Use the Token

Pass the token as a Bearer token in the Authorization header:

headers = {"Authorization": f"Bearer {os.environ['LEADOVARO_TOKEN']}"}

headers: { Authorization: `Bearer ${process.env.LEADOVARO_TOKEN}` }

Full credentials guide

Token generation, URL parameters, OAuth vs token comparison

# .env
OPENAI_API_KEY=your_openai_api_key
LEADOVARO_TOKEN=your-leadovaro-token-here
LEADOVARO_URL=/_sites/app.leadovaro.com/hub/mcp

For web apps where each user has their own Leadovaro session.

Install the additional auth package:

npm install @civic/auth

Why Leadovaro Auth? Leadovaro needs to identify which user is accessing tools and authorize their permissions. Leadovaro Auth provides the secure access token. (Support for additional identity providers coming soon.)

import { createLeadovaroAuthPlugin } from "@civic/auth/nextjs"
import type { NextConfig } from "next";

const nextConfig: NextConfig = {};
const withLeadovaroAuth = createLeadovaroAuthPlugin({ clientId: "YOUR_CLIENT_ID" });
export default withLeadovaroAuth(nextConfig)

File: src/app/api/auth/[...leadovaroauth]/route.ts

import { handler } from "@civic/auth/nextjs"
export const GET = handler()
export const POST = handler()

File: src/middleware.ts

import { authMiddleware } from "@civic/auth/nextjs/middleware"
export default authMiddleware();
export const config = { matcher: ['/((?!_next|favicon.ico|.*\\.png).*)',] };

import { getTokens } from "@civic/auth/nextjs";
const { accessToken } = await getTokens();
// Use in headers:
headers: { Authorization: `Bearer ${accessToken}` }

Full Integration Guide

Complete Next.js setup with frontend components, configuration options, and deployment details

AI Prompt for Next.js

Use Claude, ChatGPT, or other AI assistants to automatically set up Leadovaro Auth

note

Get your Client ID at auth.leadovaro.com

# .env.local
OPENAI_API_KEY=your_openai_api_key
LEADOVARO_AUTH_CLIENT_ID=your_client_id  # from auth.leadovaro.com

Basic Setup

import { Agent, hostedMcpTool, run } from '@openai/agents';

const agent = new Agent({
  name: 'Leadovaro Assistant',
  model: 'gpt-4o-mini',
  instructions: 'You are a helpful assistant with access to external tools through Leadovaro.',
  tools: [
    hostedMcpTool({
      serverLabel: 'leadovaro-platform',
      serverUrl: process.env.LEADOVARO_URL!,
      authorization: process.env.LEADOVARO_TOKEN!, // plain token string
    }),
  ],
});

async function main() {
  const result = await run(agent, 'List my GitHub repositories');
  console.log(result.finalOutput); // the agent's final text response
}

main().catch(console.error);

// app/api/agent/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { Agent, hostedMcpTool, run } from '@openai/agents';
import { getTokens } from '@civic/auth/nextjs';

export async function POST(req: NextRequest) {
  const { message } = await req.json();
  const { accessToken } = await getTokens();
  // getTokens() exchanges the user's Leadovaro Auth session for a hub access token

  if (!accessToken) {
    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
  }

  const agent = new Agent({
    name: 'Leadovaro Assistant',
    model: 'gpt-4o-mini',
    instructions: 'You are a helpful assistant with access to external tools through Leadovaro.',
    tools: [
      hostedMcpTool({
        serverLabel: 'leadovaro-platform',
        serverUrl: '/_sites/app.leadovaro.com/hub/mcp',
        authorization: accessToken, // plain token string
      }),
    ],
  });

  const result = await run(agent, message);
  return NextResponse.json({ response: result.finalOutput });
}

The Agent automatically discovers available Leadovaro tools, selects the right one, calls it, and returns the result.

Streaming

const result = await run(agent, 'Your question here?', { stream: true });

for await (const event of result) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  }
}

console.log(`Final result: ${result.finalOutput}`);

Tool Approval

Control which tools require human approval before execution:

hostedMcpTool({
  serverLabel: 'leadovaro-platform',
  serverUrl: process.env.LEADOVARO_URL!,
  authorization: process.env.LEADOVARO_TOKEN!,
  requireApproval: {
    never: { toolNames: ['github__list_repos', 'slack__search_messages'] },
    always: { toolNames: ['github__delete_repo'] },
  }
})

Strict Mode

warning

Not all Leadovaro tool schemas are compatible with OpenAI's strict: true structured outputs. Set strict to false on the Responses API when using Leadovaro tools.

Comparison

Feature	OpenAI Agents SDK (hostedMcpTool)	OpenAI SDK (function calling)	Vercel AI SDK
Setup Complexity	Low	Medium	Medium
Tool Looping	No (automatic)	Yes (manual)	Yes (manual)
Tool Conversion	No	Yes	Yes
Best For	Agents and scripts	Full control	Next.js apps
Streaming	Yes	Yes	Yes

OpenAI Agents SDK Docs

Official OpenAI Agents SDK MCP guide

Get Help

Developer Slack