DataGen SDK

Build scalable automations with the DataGen Python and TypeScript SDKs

The DataGen SDK lets you execute MCP tools programmatically from your own codebase. While the DataGen MCP server handles discovery and interactive use, the SDK enables production-ready scripts, batch processing, and scheduled automations at scale.

Why Use the SDK?

You’ve already connected your MCP servers through DataGen. Now you need to use those tools in production code without reimplementing authentication flows or managing credentials.

The core problem: When you scale beyond simple MCP tool calls, you hit limitations:

Challenge	Without SDK	With DataGen SDK
Batch operations	Sequential MCP calls, token explosion	Parallel execution, local data handling
Large datasets	50K leads = 50K API round-trips	Process locally, summarize results
Credential management	Scatter API keys across codebases	Single DATAGEN_API_KEY, auth handled by gateway
Error handling	Ad-hoc retry logic per service	Built-in exponential backoff
Production deployment	Custom auth code per provider	Same code in dev and prod

The SDK advantage:

MCP Tool Call (interactive):
  User request → LLM → MCP tool → Result → LLM → Response
  Each call flows through LLM context (expensive for large operations)

SDK Execution (production):
  Your code → DatagenClient.executeTool() → Gateway → Result
  Data stays local, only final results matter

When to Use SDK vs MCP Tools

Use MCP Tools When

• Interactive discovery and debugging
• Simple one-off operations
• Learning tool schemas with getToolDetails
• AI agent-assisted development

Use SDK When

• Batch processing (100+ operations)
• Scheduled jobs and cron tasks
• CI/CD pipelines
• Production applications
• Large data processing

Rule of thumb:

• < 5 tool calls, small results - Direct MCP tool call
• > 5 calls, large data, complex logic - Write code using SDK

---

Installation

Python

Quick Install

pip install datagen-python-sdk

With Virtual Environment (Recommended)

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install datagen-python-sdk

Set Your API Key

Get your API key from datagen.dev/account?tab=api:

export DATAGEN_API_KEY="your_api_key_here"

Verify Installation

python -c "from datagen_sdk import DatagenClient; print('SDK installed successfully')"

MCP Prompt Installation: If you’re using Claude Code with DataGen MCP, you can run the install-datagen-python-sdk prompt to get guided installation steps.

TypeScript

Quick Install

npm

npm install @datagen-dev/typescript-sdk

Requirements

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

Set Your API Key

Get your API key from datagen.dev/account?tab=api:

export DATAGEN_API_KEY="your_api_key_here"

Verify Installation

node -e "import('@datagen-dev/typescript-sdk').then(() => console.log('SDK installed successfully'))"

MCP Prompt Installation: If you’re using Claude Code with DataGen MCP, you can run the install-datagen-typescript-sdk prompt to get guided installation steps.

---

Quick Start

Python

from datagen_sdk import DatagenClient

client = DatagenClient()

# Send an email through Gmail MCP
result = client.execute_tool(
    "mcp_Gmail_gmail_send_email",
    {
        "to": "[e-mail]",
        "subject": "Hello from DataGen",
        "body": "This email was sent using the DataGen SDK!"
    }
)

print(result)

TypeScript

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

const client = new DatagenClient();

// Send an email through Gmail MCP
const result = await client.executeTool(
    "mcp_Gmail_gmail_send_email",
    {
        to: "[e-mail]",
        subject: "Hello from DataGen",
        body: "This email was sent using the DataGen SDK!"
    }
);

console.log(result);

---

Examples

Batch Email Campaign

Process contacts and send personalized emails:

Python

from datagen_sdk import DatagenClient

client = DatagenClient()

# Get contacts from database
contacts = client.execute_tool(
    "mcp_Supabase_run_sql",
    {
        "params": {
            "sql": "SELECT email, name FROM users WHERE signup_date > NOW() - INTERVAL '7 days'",
            "projectId": "your-project-id",
            "databaseName": "your-db"
        }
    }
)

# Send personalized emails
for contact in contacts:
    client.execute_tool(
        "mcp_Gmail_gmail_send_email",
        {
            "to": contact["email"],
            "subject": "Welcome!",
            "body": f"Hi {contact['name']}, thanks for signing up!"
        }
    )
    print(f"Sent to {contact['email']}")

TypeScript

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

const client = new DatagenClient();

// Get contacts from database
const contacts = await client.executeTool(
    "mcp_Supabase_run_sql",
    {
        params: {
            sql: "SELECT email, name FROM users WHERE signup_date > NOW() - INTERVAL '7 days'",
            projectId: "your-project-id",
            databaseName: "your-db"
        }
    }
);

// Send personalized emails
for (const contact of contacts) {
    await client.executeTool(
        "mcp_Gmail_gmail_send_email",
        {
            to: contact.email,
            subject: "Welcome!",
            body: `Hi ${contact.name}, thanks for signing up!`
        }
    );
    console.log(`Sent to ${contact.email}`);
}

Error Handling

Handle authentication and tool execution errors:

Python

from datagen_sdk import DatagenClient, DatagenAuthError, DatagenToolError

client = DatagenClient(
    retries=3,           # Retry up to 3 times
    backoff_seconds=0.5  # Exponential backoff
)

try:
    result = client.execute_tool(
        "mcp_Linear_list_projects",
        {"limit": 10}
    )
    print(result)
except DatagenAuthError:
    print("Authentication failed - check your API key or MCP connection")
except DatagenToolError as e:
    print(f"Tool execution failed: {e.message}")

TypeScript

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

const client = new DatagenClient({
    retries: 3,           // Retry up to 3 times
    backoffSeconds: 0.5   // Exponential backoff
});

try {
    const result = await client.executeTool(
        "mcp_Linear_list_projects",
        { limit: 10 }
    );
    console.log(result);
} catch (error) {
    if (error instanceof DatagenAuthError) {
        console.error("Authentication failed - check your API key or MCP connection");
    } else if (error instanceof DatagenToolError) {
        console.error(`Tool execution failed: ${error.message}`);
    }
}

Multi-Service Workflow

Combine multiple MCP tools in a single workflow:

Python

from datagen_sdk import DatagenClient

client = DatagenClient()

# 1. Fetch high-priority leads from database
leads = client.execute_tool(
    "mcp_Supabase_run_sql",
    {
        "params": {
            "sql": "SELECT * FROM leads WHERE score > 80",
            "projectId": "your-project",
            "databaseName": "your-db"
        }
    }
)

# 2. Create tasks in Linear for each lead
for lead in leads:
    issue = client.execute_tool(
        "mcp_Linear_create_issue",
        {
            "title": f"Follow up with {lead['company']}",
            "description": f"Contact: {lead['email']}\nScore: {lead['score']}",
            "teamId": "your-team-id"
        }
    )
    print(f"Created Linear issue: {issue['id']}")

# 3. Notify team on Slack
client.execute_tool(
    "mcp_Slack_chat_postMessage",
    {
        "channel": "#sales",
        "text": f"Created {len(leads)} follow-up tasks for high-priority leads"
    }
)

TypeScript

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

const client = new DatagenClient();

// 1. Fetch high-priority leads from database
const leads = await client.executeTool(
    "mcp_Supabase_run_sql",
    {
        params: {
            sql: "SELECT * FROM leads WHERE score > 80",
            projectId: "your-project",
            databaseName: "your-db"
        }
    }
);

// 2. Create tasks in Linear for each lead
for (const lead of leads) {
    const issue = await client.executeTool(
        "mcp_Linear_create_issue",
        {
            title: `Follow up with ${lead.company}`,
            description: `Contact: ${lead.email}\nScore: ${lead.score}`,
            teamId: "your-team-id"
        }
    );
    console.log(`Created Linear issue: ${issue.id}`);
}

// 3. Notify team on Slack
await client.executeTool(
    "mcp_Slack_chat_postMessage",
    {
        channel: "#sales",
        text: `Created ${leads.length} follow-up tasks for high-priority leads`
    }
);

---

API Reference

Client Configuration

Python

from datagen_sdk import DatagenClient

client = DatagenClient(
    api_key=None,           # Default: from DATAGEN_API_KEY env var
    base_url="https://api.datagen.dev",
    timeout=30,             # Request timeout in seconds
    retries=0,              # Retry attempts for failed requests
    backoff_seconds=0.5     # Initial backoff for retries
)

TypeScript

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

const client = new DatagenClient({
    apiKey: undefined,      // Default: from DATAGEN_API_KEY env var
    baseUrl: "https://api.datagen.dev",
    timeout: 30000,         // Request timeout in ms
    retries: 0,             // Retry attempts for failed requests
    backoffSeconds: 0.5     // Initial backoff for retries
});

Execute Tool

The primary method for calling MCP tools:

Python

result = client.execute_tool(
    tool_alias_name: str,   # e.g., "mcp_Gmail_gmail_send_email"
    parameters: dict = {}   # Tool-specific parameters
)

TypeScript

const result = await client.executeTool(
    toolAliasName: string,              // e.g., "mcp_Gmail_gmail_send_email"
    parameters?: Record<string, any>    // Tool-specific parameters
);

Error Types

Error	Description
DatagenAuthError	Authentication failed (401/403) - check API key or MCP connection
DatagenToolError	Tool execution failed - check parameters match schema
DatagenHttpError	Network or HTTP-level errors

---

Best Practices

Always discover tool schemas first

Before writing production code, use the getToolDetails MCP tool to confirm exact parameter names and types:

# Via MCP or SDK
details = client.execute_tool("getToolDetails", {"tool_name": "mcp_Gmail_gmail_send_email"})
print(details["inputSchema"])

Use environment variables for API keys

Never hardcode API keys in your code. The SDK automatically reads from DATAGEN_API_KEY:

export DATAGEN_API_KEY="your_api_key_here"

Enable retries for production

Configure retries and backoff for resilient production code:

client = DatagenClient(retries=3, backoff_seconds=1.0)

Handle errors gracefully

Wrap tool calls in try/except and handle specific error types:

try:
    result = client.execute_tool("mcp_Gmail_gmail_send_email", {...})
except DatagenAuthError:
    # Re-authenticate or check MCP connection
except DatagenToolError as e:
    # Log error and retry with corrected params

---

Resources

Python SDK

Source code, examples, and documentation

TypeScript SDK

Source code, examples, and documentation

Get API Key

Generate your DataGen API key

Connect MCP Servers

Add Gmail, Slack, Linear, and more