@datagen-dev/typescript-sdk

Built for AI coding assistants and developers. DataGen's MCP server lets AI agents discover and understand how to use any integrated tool - Gmail, Linear, Supabase, Slack - without hardcoded integration knowledge. Agents use searchTools and getToolDetails to self-guide, writing clean client.executeTool() code that skips SDK hell, OAuth nightmares, and API integration boilerplate.

Key Features

• MCP Tools as Code: Turn any MCP tool into executable code - no SDK installation, no API wrappers
• Skip Integration Hell: No Gmail SDK, no LinkedIn API wrappers, no OAuth configuration code
• One Client for Everything: Access Gmail, Linear, Supabase, Slack - same simple pattern
• MCP Gateway: Unified authentication for all connected MCP servers. You don't need to handle auth during the code generation process.
• MCP Middleware: Built-in retry logic and rate-limit handling across all your API calls

Deep Dive: See WHY_DATAGEN.md for a detailed comparison of DataGen SDK vs direct API integration, including security benefits, credential management, and code examples.

AI Agent-First Design

DataGen is built for AI coding assistants (Claude, Cursor, Copilot, etc.) to discover and use tools without hardcoded knowledge.

DataGen's MCP Gateway architecture - one client handles auth and routing to Gmail, Supabase, LinkedIn. Write simple executeTool() calls, skip all SDK setup

The Agent Discovery Workflow

Step 1: Agent discovers available tools

Agent calls searchTools MCP tool:
Input: "send email"
Output: ['mcp_Gmail_gmail_send_email', 'mcp_Resend_send_email', ...]

Step 2: Agent learns tool schema

Agent calls getToolDetails MCP tool:
Input: "mcp_Gmail_gmail_send_email"
Output: {
  "name": "mcp_Gmail_gmail_send_email",
  "inputSchema": {
    "properties": {
      "to": {"type": "string"},
      "subject": {"type": "string"},
      "body": {"type": "string"}
    }
  }
}

Step 3: Agent writes clean code

client.executeTool(
    "mcp_Gmail_gmail_send_email",
    {
        to: user.email,
        subject: "Welcome!",
        body: `Hi ${user.name}, thanks for signing up!`
    }
)

How DataGen Transforms AI-Assisted Development

DataGen's MCP + SDK combo dramatically improves agent-assisted coding by eliminating the gap between "what you want" and "working code."

🎯 The AI-Assisted Experience:

Just tell your AI agent: "Send an email to new signups from the database"

The agent instantly:

1. Self-discovers tools via MCP (searchTools finds mcp_Supabase_run_sql, mcp_Gmail_gmail_send_email)
2. Learns schemas via MCP (getToolDetails gets exact parameters needed)
3. Writes clean code using the SDK (client.executeTool() calls)
4. Executes immediately - no OAuth, no API key setup, no SDK installation, no API docs hunting

Traditional AI-Assisted Development Problems:

• ❌ Agent generates Gmail SDK boilerplate → you fix OAuth errors for 30 minutes
• ❌ Agent hallucinates API parameters → you debug incorrect field names
• ❌ Agent imports wrong packages → you install 5 SDKs and resolve conflicts
• ❌ You iterate 10+ times to get working integration code

DataGen AI-Assisted Development Reality:

• ✅ Agent self-discovers real tools and schemas → generates correct code first try
• ✅ Zero OAuth & API key configuration → authentication handled by MCP Gateway
• ✅ One SDK for everything → no package conflicts or version hell
• ✅ You iterate on business logic, not integration plumbing

The Result: Go from idea → working integration in one prompt instead of one hour.

Real-World Integration Comparison

Task: Send welcome emails and Slack notifications for new database signups

Without DataGen - Multiple packages, credential management, service-specific boilerplate:

import { google } from 'googleapis';
import { OAuth2Client } from 'google-auth-library';
import { WebClient } from '@slack/web-api';
import postgres from 'postgres';

// OAuth & service setup
const oauth2Client = new OAuth2Client(
  process.env.GMAIL_CLIENT_ID,
  process.env.GMAIL_CLIENT_SECRET,
  'http://localhost'
);
oauth2Client.setCredentials({ refresh_token: process.env.GMAIL_REFRESH_TOKEN });

const gmail = google.gmail({ version: 'v1', auth: oauth2Client });
const slack = new WebClient(process.env.SLACK_TOKEN);

// Database connection & query
const sql = postgres({
  host: '...',
  user: process.env.DB_USER,
  password: process.env.DB_PASS
});

const users = await sql`SELECT email, name FROM users WHERE created_at > NOW() - INTERVAL '1 day'`;

// Send emails with base64 encoding
for (const user of users) {
  const message = [
    'Content-Type: text/plain; charset="UTF-8"\n',
    'MIME-Version: 1.0\n',
    `To: ${user.email}\n`,
    'Subject: Welcome\n\n',
    `Hi ${user.name}!`
  ].join('');

  const encodedMessage = Buffer.from(message).toString('base64').replace(/\+/g, '-').replace(/\//g, '_');
  await gmail.users.messages.send({ userId: 'me', requestBody: { raw: encodedMessage } });
  await slack.chat.postMessage({ channel: '#signups', text: `New: ${user.name}` });
}

With DataGen - Single client, managed authentication, clean code:

import { DatagenClient } from '@datagen-dev/typescript-sdk';

const client = new DatagenClient();
const users = await client.executeTool("mcp_Supabase_run_sql", {
  params: {
    sql: "SELECT email, name FROM users WHERE created_at > NOW() - INTERVAL '1 day'"
  }
});

for (const user of users) {
  await client.executeTool("mcp_Gmail_gmail_send_email", {
    to: user.email,
    subject: "Welcome",
    body: `Hi ${user.name}!`
  });
  await client.executeTool("mcp_Slack_chat_postMessage", {
    channel: "#signups",
    text: `New: ${user.name}`
  });
}

The Difference:

• Package Management: Installing & managing googleapis, postgres, @slack/web-api → One @datagen-dev/typescript-sdk
• Authentication: OAuth token files, database credentials, API keys scattered across your codebase → MCP Gateway handles all auth
• Boilerplate Code: Service-specific patterns (base64 encoding, OAuth clients, connection pooling) → Clean executeTool() for everything

Quick Start

1. Add DataGen MCP to Your Coding Agent

Connect DataGen as an MCP server to your AI coding assistant (Cursor, Claude Code, etc.) to enable tool discovery and execution directly from your editor. (Go to https://datagen.dev/account?tab=api for api key)

Standard Configuration:

{
  "mcpServers": {
    "datagen": {
      "url": "https://mcp.datagen.dev/mcp",
      "headers": {
        "x-api-key": "${DATAGEN_API_KEY}"
      }
    }
  }
}

Client-Specific Setup:

Quick Setup:

1. Open Cursor Settings → Features → Beta → Model Context Protocol
2. Click "Add MCP Server"
3. Configure with OAuth:
   • Name: datagen
   • Transport: SSE
   • URL: https://mcp.datagen.dev/mcp
   • Auth: Select OAuth

Cursor will handle OAuth authentication automatically when you first use DataGen tools.

Alternative - Manual Config:

Add to your Cursor MCP config file (~/.cursor/config.json or via Settings):

{
  "mcpServers": {
    "datagen": {
      "type": "sse",
      "url": "https://mcp.datagen.dev/mcp",
      "auth": "oauth"
    }
  }
}

Note: If you're viewing this in Cursor, you can use this deep link: cursor://anysphere.cursor-deeplink/mcp/install?name=datagen&config=eyJ0eXBlIjoic3NlIiwidXJsIjoiaHR0cHM6Ly9tY3AuZGF0YWdlbi5kZXYvbWNwIiwiYXV0aCI6Im9hdXRoIn0%3D

Use the CLI command with HTTP transport:

claude mcp add --transport http datagen https://mcp.datagen.dev/mcp --header "x-api-key: YOUR_API_KEY"

Verify with:

claude mcp list

Config File Location: ~/.gemini/settings.json

Add this configuration for HTTP Streaming:

{
  "mcpServers": {
    "datagen": {
      "httpUrl": "https://mcp.datagen.dev/mcp",
      "headers": {
        "x-api-key": "$DATAGEN_API_KEY"
      },
      "timeout": 5000
    }
  }
}

Config File Location: ~/.codex/config.toml

Add this configuration for Streamable HTTP:

[mcp_servers.datagen]
url = "https://mcp.datagen.dev/mcp"
env_http_headers = { "x-api-key" = "DATAGEN_API_KEY" }

Then set your environment variable:

export DATAGEN_API_KEY=your_api_key_here

Or use static headers directly:

[mcp_servers.datagen]
url = "https://mcp.datagen.dev/mcp"
http_headers = { "x-api-key" = "your_api_key_here" }

Verifying the Connection:

Once configured, try asking your AI assistant:

• "What tools are available through DataGen?"
• "List my Linear projects using DataGen"
• "Send an email via Gmail through DataGen"

Your AI will use searchTools and getToolDetails MCP tools to discover and execute DataGen tools automatically.

2. Add Desired MCP Servers to DataGen

Connect the MCP servers you want to use (Gmail, Linear, Supabase, Slack, etc.):

1. Go to https://datagen.dev
2. Navigate to MCP Servers section
3. Click Add MCP Server
4. Choose from available MCP servers (examples include):
   • Gmail MCP: Connect your Gmail account via OAuth
   • Supabase MCP: Connect your Supabase database
   • Linear MCP: Connect your Linear workspace
   • Slack MCP: Connect your Slack workspace
   • And many more - you can add any MCP server you need
5. Complete the authentication flow for each service

Once connected, all tools from these MCP servers become available through the DataGen SDK. You never touch credentials in your code - DataGen's MCP Gateway handles all authentication.

3. Install the TypeScript SDK

npm install @datagen-dev/typescript-sdk

yarn add @datagen-dev/typescript-sdk

pnpm add @datagen-dev/typescript-sdk

4. Configure Your DataGen API Key

export DATAGEN_API_KEY=your_api_key_here

5. Let Your AI Agent Write Integrations

Now you're ready! Just ask your AI coding assistant to build with DataGen:

Example prompt: "Build a script that sends an email to new signups from the database using DataGen SDK"

Your AI will:

1. Self-discover the right tools using searchTools (finds mcp_Supabase_run_sql, mcp_Gmail_gmail_send_email)
2. Learn the schemas using getToolDetails (gets exact parameters)
3. Write clean code using client.executeTool()
4. Generate working code in one shot

The generated code will look like:

import { DatagenClient } from '@datagen-dev/typescript-sdk';

const client = new DatagenClient();

// Query database for new signups
const newUsers = await client.executeTool(
    "mcp_Supabase_run_sql",
    {
        params: {
            sql: "SELECT email, name FROM users WHERE created_at > NOW() - INTERVAL '1 day'",
            projectId: "your-project-id",
            databaseName: "your-db"
        }
    }
);

// Send welcome email via Gmail
for (const user of newUsers) {
    await client.executeTool(
        "mcp_Gmail_gmail_send_email",
        {
            to: user.email,
            subject: "Welcome!",
            body: `Hi ${user.name}, thanks for signing up!`
        }
    );
}

That's it! No OAuth setup, no SDK installation, no API docs hunting. Just working code.

Examples

Example 1: Send Welcome Emails to New Signups

Query your database and send emails - no database drivers, no OAuth setup:

import { DatagenClient } from '@datagen-dev/typescript-sdk';

const client = new DatagenClient();

// Query Supabase database for new signups
const newUsers = await client.executeTool(
    "mcp_Supabase_run_sql",
    {
        params: {
            sql: "SELECT email, name FROM users WHERE created_at > NOW() - INTERVAL '1 day'",
            projectId: "your-project-id",
            databaseName: "your-db"
        }
    }
);

// Send welcome email via Gmail
for (const user of newUsers) {
    await client.executeTool(
        "mcp_Gmail_gmail_send_email",
        {
            to: user.email,
            subject: "Welcome!",
            body: `Hi ${user.name}, thanks for signing up!`
        }
    );
}

Example 2: Batch Processing with Error Handling

Process multiple items with built-in retry logic:

import { DatagenClient, DatagenToolError } from '@datagen-dev/typescript-sdk';

const client = new DatagenClient({
  retries: 3,
  backoffSeconds: 0.5
});

// Load high-priority contacts from database
const contacts = await client.executeTool("mcp_Supabase_run_sql", {
  params: {
    sql: "SELECT * FROM crm WHERE priority_score > 75",
    projectId: "your-project-id",
    databaseName: "your-db"
  }
});

// Send follow-up emails with error handling
for (const contact of contacts) {
  try {
    await client.executeTool("mcp_Gmail_gmail_send_email", {
      to: contact.email,
      subject: "Follow-up",
      body: "Just checking in..."
    });
    console.log(`✓ Sent to ${contact.email}`);
  } catch (error) {
    if (error instanceof DatagenToolError) {
      console.error(`✗ Failed to send to ${contact.email}: ${error.message}`);
    } else {
      throw error;
    }
  }
}

Key Benefits: No database connection setup, no Gmail OAuth, no SDK installation. Same executeTool() pattern for all services.

API Reference

DatagenClient

The main client class for interacting with the Datagen API.

Constructor

new DatagenClient(config?: DatagenClientConfig)

Configuration Options:

interface DatagenClientConfig {
  apiKey?: string;          // API key (default: from DATAGEN_API_KEY env var)
  baseUrl?: string;         // Base URL (default: "https://api.datagen.dev")
  timeout?: number;         // Request timeout in ms (default: 30000)
  retries?: number;         // Retry attempts (default: 0)
  backoffSeconds?: number;  // Backoff time for retries (default: 0.5)
}

Throws:

• DatagenAuthError: If API key is not provided and DATAGEN_API_KEY is not set

Examples:

// Basic usage (reads API key from environment)
const client = new DatagenClient();

// Custom base URL
const client = new DatagenClient({
  baseUrl: 'https://api.datagen.dev'
});

// With retry logic
const client = new DatagenClient({
  retries: 3,              // Retry up to 3 times
  backoffSeconds: 1.0      // Start with 1 second, doubles each retry
});

// Custom timeout
const client = new DatagenClient({
  timeout: 60000  // 60 second timeout
});

Methods

executeTool

Execute a DataGen tool by its alias name.

async executeTool(
  toolAliasName: string,
  parameters?: Record<string, any>
): Promise<any>

Parameters:

• toolAliasName (string): The alias name of the tool to execute (e.g., "mcp_Linear_list_projects")
• parameters (object, optional): Parameters to pass to the tool. Default: {}

Returns:

• The result data from the tool execution

Throws:

• DatagenAuthError: Authentication failed (401/403)
• DatagenHttpError: HTTP-level errors (network issues, 4xx/5xx status codes)
• DatagenToolError: Tool executed but reported a failure

Example:

const result = await client.executeTool('mcp_Linear_list_projects', {
  limit: 20
});

Error Handling

The SDK provides specific exception types for different error scenarios:

import {
  DatagenClient,
  DatagenError,          // Base exception
  DatagenAuthError,      // Authentication errors
  DatagenHttpError,      // HTTP-level errors
  DatagenToolError       // Tool execution errors
} from '@datagen-dev/typescript-sdk';

try {
  const client = new DatagenClient();
  const result = await client.executeTool('my_tool', { param: 'value' });
} catch (error) {
  if (error instanceof DatagenAuthError) {
    console.error('Authentication failed:', error.message);
  } else if (error instanceof DatagenToolError) {
    console.error('Tool execution failed:', error.message);
  } else if (error instanceof DatagenHttpError) {
    console.error('HTTP error:', error.message);
  } else if (error instanceof DatagenError) {
    console.error('General error:', error.message);
  }
}

Requirements

• Node.js >= 18.0.0 (for native fetch support)
• TypeScript >= 5.0 (if using TypeScript)

Development

Running Examples

See the examples/ directory for complete examples:

# Set your API key
export DATAGEN_API_KEY=your_api_key_here

# Build the SDK first
npm run build

# Run examples (requires Node.js 18+)
node examples/list-projects.js
node examples/list-issues.js

Building

npm run build

Testing

npm test                 # Run tests once
npm run test:watch       # Run tests in watch mode
npm run test:ui          # Run tests with UI

Type Checking

npm run type-check

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• Homepage: https://datagen.dev
• Source Code: https://github.com/datagen/datagen-typescript-sdk
• Issue Tracker: https://github.com/datagen/datagen-typescript-sdk/issues
• NPM Package: https://www.npmjs.com/package/@datagen-dev/typescript-sdk

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.