How to Give a Mastra Agent B2B Data (REST Tools and MCP)

npm install @mastra/core@latest zod@^4
npm install -D typescript @types/node mastra@latest

LEADOCEAN_API_KEY=paste-your-leadocean-key
OPENAI_API_KEY=paste-your-model-key

// src/mastra/lib/leadocean.ts
const BASE = 'https://api.leadocean.io'
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))

export type LoOk = { ok: true; data: any; meta: any; records: number }
export type LoErr = { ok: false; code: string; message: string; retryAfter?: number }

export async function lo(
  path: string,
  opts: { method?: 'GET' | 'POST'; query?: Record<string, string | number | boolean>; body?: object } = {},
): Promise<LoOk | LoErr> {
  const url = new URL(path, BASE)
  for (const [k, v] of Object.entries(opts.query ?? {})) url.searchParams.set(k, String(v))

  for (let attempt = 0; attempt < 3; attempt++) {
    const res = await fetch(url, {
      method: opts.method ?? 'POST',
      headers: { 'x-api-key': process.env.LEADOCEAN_API_KEY!, 'content-type': 'application/json' },
      body: opts.body ? JSON.stringify(opts.body) : undefined,
    })
    const json: any = await res.json().catch(() => null)
    if (res.ok) return { ok: true, data: json.data, meta: json.meta ?? {}, records: json.meta?.credits ?? 0 }

    const message = json?.error?.message ?? res.statusText
    if (res.status === 401) return { ok: false, code: 'bad_key', message }
    if (res.status === 402) return { ok: false, code: 'out_of_records', message }
    if (res.status === 404) return { ok: false, code: 'not_found', message }
    if (res.status === 400) return { ok: false, code: 'bad_request', message: JSON.stringify(json?.error?.details ?? message) }
    if (res.status === 429) {
      const retryAfter = Number(res.headers.get('retry-after') ?? 1)
      if (retryAfter <= 2 && attempt < 2) { await sleep(retryAfter * 1000); continue }
      return { ok: false, code: 'throttled', message, retryAfter }
    }
    if (res.status === 503) { await sleep(2 ** attempt * 1000); continue }
    return { ok: false, code: `http_${res.status}`, message }
  }
  return { ok: false, code: 'unavailable', message: 'LeadOcean did not answer after 3 tries' }
}

// src/mastra/tools/leadocean.ts
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'
import { lo } from '../lib/leadocean'

const filters = z.object({
  title: z.array(z.string()).optional().describe('Job title keywords, e.g. ["Head of Sales"]'),
  jobLevel: z.array(z.enum(['C-Team', 'VP', 'Director', 'Manager', 'Staff', 'Other'])).optional(),
  country: z.array(z.string().length(2)).optional().describe('ISO 3166-1 alpha-2, e.g. ["CA"]'),
  domain: z.array(z.string()).optional().describe('Company domains, e.g. ["acme.com"]'),
  emailStatus: z.array(z.string()).default(['verified']),
  emailType: z.array(z.string()).default(['work']),
})

export function makeLeadOceanTools(maxRecords = 25) {
  let spent = 0
  const overBudget = (need: number) =>
    spent + need > maxRecords
      ? { ok: false, code: 'run_budget', message: `Run cap of ${maxRecords} records reached (${spent} spent).` }
      : null

  const countPeople = createTool({
    id: 'count-people',
    description: 'Free. Count people matching filters before searching. Total is capped at 100,000.',
    inputSchema: filters,
    execute: async (f) => {
      const r = await lo('/v1/people/search', { query: { count: true }, body: { ...f, limit: 1 } })
      return r.ok ? { total: r.meta.total, totalIsExact: r.meta.totalIsExact } : r
    },
  })

  const searchPeople = createTool({
    id: 'search-people',
    description: 'Find people. Costs 1 record per person returned. Returns no email addresses.',
    inputSchema: filters.extend({ limit: z.number().int().min(1).max(10).default(5) }),
    execute: async (f) => {
      const blocked = overBudget(f.limit)
      if (blocked) return blocked
      const r = await lo('/v1/people/search', { body: f })
      if (!r.ok) return r
      spent += r.records
      return {
        spent,
        people: r.data.map((p: any) => ({
          person_id: p.meta?.source_ids?.person_id,
          name: p.profile_data?.profile_full_name,
          title: p.contact_data?.contact_current_experiences?.[0]?.job_title,
          company: p.contact_data?.contact_current_experiences?.[0]?.company_name,
          has_email: p.contact_data?.has_email,
          email_status: p.contact_data?.email_status,
        })),
      }
    },
  })

  const enrichPerson = createTool({
    id: 'enrich-person',
    description: 'Get the email for one person from search. Costs 1 record. Pass the person_id.',
    inputSchema: z.object({ person_id: z.string().regex(/^[1-9][0-9]{0,19}$/) }),
    execute: async ({ person_id }) => {
      const blocked = overBudget(1)
      if (blocked) return blocked
      const r = await lo('/v1/people/enrich', { body: { person_id, reveal_email: true } })
      if (!r.ok) return r
      spent += r.records
      return { spent, emails: r.data.contact_data?.contact_emails ?? [] }
    },
  })

  return { countPeople, searchPeople, enrichPerson }
}

// src/mastra/agents/prospect-agent.ts
import { Agent } from '@mastra/core/agent'
import { makeLeadOceanTools } from '../tools/leadocean'

export function makeProspectAgent() {
  return new Agent({
    id: 'prospect-agent',
    name: 'Prospect Agent',
    instructions: `
      You find B2B contacts with LeadOcean tools.
      Always call count-people first and report the total.
      Then search-people with a limit of 10 or less.
      Enrich at most 3 people, only if the user asks for emails.
      If a tool returns ok:false, stop and tell the user the code and message. Do not retry.
    `,
    model: 'openai/gpt-5.6-sol',
    tools: makeLeadOceanTools(25),
  })
}

// src/run.ts
import { makeProspectAgent } from './mastra/agents/prospect-agent'

const agent = makeProspectAgent()
const result = await agent.generate(
  'VPs and C-Team in Canada. How many are mailable? Show 5 and get emails for 2.',
  { maxSteps: 8 },
)
console.log(result.text)

// src/mastra/mcp/leadocean.ts
import { MCPClient } from '@mastra/mcp'

export const leadoceanMcp = new MCPClient({
  id: 'leadocean',
  servers: {
    leadocean: { url: new URL('https://api.leadocean.io/mcp') },
  },
})

// in the agent: tools: await leadoceanMcp.listTools()

{ "total": 15322, "totalIsExact": true, "totalAll": 75629, "credits": 0 }

{
  "success": true,
  "data": [
    {
      "profile_data": { "profile_full_name": "Jane Doe", "profile_url": "https://www.linkedin.com/in/janedoe-example" },
      "contact_data": {
        "has_email": true,
        "email_status": "verified",
        "email_type": "work",
        "contact_current_experiences": [{ "job_title": "VP Sales", "company_name": "Acme", "company_domain": "acme.com" }]
      },
      "meta": { "source_ids": { "person_id": "12345678" } }
    }
  ],
  "meta": { "count": 1, "limit": 5, "credits": 1, "nextCursor": "..." }
}