latam-synth

Privacy-safe synthetic financial data for Latin American fintech — available through Python, CLI, REST, Apify Actor, and Model Context Protocol (MCP) for AI agents.

Synthetic generator of financial savings behavior data, calibrated with the statistical distributions of 506,311 real records from a LatAm savings app (2015–2024): 305,808 transactions, 108,570 savings goals and 91,933 users from Mexico, Colombia, Argentina, Peru, Chile and more.

The output is 100% synthetic: no record derives from a real user, only from aggregate distributions. No PII and no re-identification risk.

Model Context Protocol (MCP)

LatAm Synth is available to AI agents as an MCP tool through two independent paths:

• Remote (hosted): the Apify MCP Server exposes the active_yardstick/latam-synth Actor as a callable MCP tool over Streamable HTTP. Nothing to install.

• Local (stdio): latam-synth-mcp, shipped in this repository, runs the generator in-process without calling Apify. For local MCP clients and containerised catalog checks.

Both paths return the same tables with the same referential integrity, because both are thin adapters over the same SyntheticGenerator.

MCP details

• MCP capability: Tools

• Transport: Streamable HTTP (remote) / stdio (local)

• Hosted MCP server: Apify MCP Server

• Local MCP server: latam-synth-mcp (extra [mcp], SDK mcp>=2,<3)

• Actor exposed as tool: active_yardstick/latam-synth

• Authentication: Apify OAuth or Bearer token

• Official MCP Registry name: io.github.jmendozapuche/latam-fintech-synthetic-data

• Registry metadata: server.json

• Apify Actor: https://apify.com/active_yardstick/latam-synth

MCP endpoint

https://mcp.apify.com?tools=active_yardstick/latam-synth

The tools parameter restricts the Apify MCP Server to the LatAm Synth Actor, making it directly discoverable and callable by compatible AI agents.

Example MCP configuration — OAuth

{
  "mcpServers": {
    "latam-synth": {
      "url": "https://mcp.apify.com?tools=active_yardstick/latam-synth"
    }
  }
}

On first connection, a compatible MCP client can open the Apify OAuth flow so the user can authorize access without placing an API token directly in the configuration.

Example MCP configuration — Bearer token

{
  "mcpServers": {
    "latam-synth": {
      "url": "https://mcp.apify.com?tools=active_yardstick/latam-synth",
      "headers": {
        "Authorization": "Bearer <APIFY_TOKEN>"
      }
    }
  }
}

Replace <APIFY_TOKEN> with an Apify API token.

What AI agents can do with LatAm Synth

An MCP-compatible agent can invoke LatAm Synth to generate:

• synthetic financial users

• linked savings goals

• deposit and withdrawal transactions

• country-filtered Latin American datasets

• reproducible datasets using a random seed

• realistic fintech test data without exposing personally identifiable information

Typical agent use cases include:

• evaluating financial AI agents

• generating test fixtures on demand

• creating synthetic datasets for demos and POCs

• testing recommendation or savings assistants

• bootstrapping ML and data-pipeline experiments

LatAm Synth currently exposes its functionality through MCP Tools. It does not currently expose MCP Resources or Prompts.

How MCP is implemented

The remote path does not require an MCP transport server inside this repository: Apify hosts it. The local path does ship one (src/latam_synth/mcp_server.py), for clients that prefer to run the generator themselves — no token, no network, no per-run cost.

The architecture is:

MCP-compatible AI client
        |
        |  Streamable HTTP
        v
Apify MCP Server
        |
        |  exposes Actor as MCP Tool
        v
active_yardstick/latam-synth
        |
        v
Synthetic users + goals + transactions

Apify provides the hosted MCP server and authentication layer. The LatAm Synth Actor provides the executable tool functionality and structured input/output.

Local MCP server (stdio)

pip install -e ".[mcp]"
latam-synth-mcp                    # entry point
python -m latam_synth.mcp_server   # equivalent

Configuration for a local MCP client (Claude Desktop / Claude Code):

{
  "mcpServers": {
    "latam-synth": {
      "command": "latam-synth-mcp"
    }
  }
}

Exposed tools:

Both are annotated read_only and idempotent: nothing is written and the same seed returns the same dataset. The 200-user cap per call keeps responses small enough for an agent context — for larger volumes use the CLI or the Actor.

Deployment detail, Docker image and Glama configuration: docs/mcp_local.md.

Related MCP server: LiveDataLink

What it's for

• Fintech testing and QA: realistic fixtures for payment pipelines, budgeting apps and goal engines.

• Demos and POCs: dashboards with plausible LatAm data that can be shown publicly.

• ML training: bootstrapping data for churn, recommendation and segmentation models with real patterns such as seasonality, abandonment rates and goal categories.

• AI agents: on-demand generation of synthetic financial datasets through MCP.

• Education: unlimited datasets for data science courses with real business narrative.

Quick usage

CLI

pip install -e .
latam-synth generate --users 5000 --seed 42 --format csv --out ./output

Mexico and Colombia only, parquet format:

latam-synth generate --users 10000 --countries Mexico Colombia --format parquet

Python

from latam_synth import SyntheticGenerator, GeneratorConfig

data = SyntheticGenerator(
    GeneratorConfig(n_users=1000, seed=42)
).generate()

data["transactions"].head()

What makes this generator faithful

The calibration was verified against real data. See:

docs/validation_report.txt

The generator incorporates:

• lognormal amount distributions by transaction type

• real monthly seasonality

• January post-resolutions peak and December valley

• 8 goal categories with their own amounts and horizons

• observed achievement and abandonment rates

• 73.8% of goals past due

• shared goals uplift

• correlated user scores

• Gaussian copula with ρ=0.89 for discipline-achievement

• coherent temporal trajectories per goal

• referential integrity between users, goals and transactions

Apify Actor

LatAm Synth is also available as a hosted Apify Actor:

active_yardstick/latam-synth

Actor page:

https://apify.com/active_yardstick/latam-synth

The Actor can be called directly from Apify, through the Apify API, or exposed to AI clients through the Apify MCP Server.

Example input:

{
  "users": 1000,
  "seed": 42,
  "countries": ["Mexico", "Colombia"],
  "format": "csv",
  "push_to_dataset": true,
  "start_date": "2023-01-01",
  "end_date": "2024-12-31"
}

The seed parameter makes generation reproducible. The same seed and configuration produce the same synthetic output.

Where to find your output (Apify)

Every run writes output to two places.

Key-value store — all three tables

1. Open the run in Apify Console and click the Storage tab.

2. Click Key-value store.

3. Download the generated files:

   • users.csv — one row per synthetic user

   • goals.csv — savings goals linked to users

   • transactions.csv — deposit/withdrawal transactions linked to goals

   • OUTPUT — always present; JSON summary of the run, including parameters, row counts and downloadable keys

   • if format: json was selected, OUTPUT_DATA contains all three tables in a single JSON file instead of the three CSV files

4. Click the download icon next to each key to save the file.

Dataset — transactions

By default (push_to_dataset: true), all transactions are also pushed to the run's Dataset.

This allows you to:

• export as JSON, CSV, or Excel directly from the Dataset tab

• connect native Apify integrations to the Dataset output

• consume transactions programmatically

To disable this for very large runs where only the key-value-store files are needed, set:

{
  "push_to_dataset": false
}

The run log prints exact file names and row counts at the end of execution.

Local REST API

Install the API dependencies:

pip install -e ".[api]"
uvicorn latam_synth.api:app --port 8000

Generate JSON with the three tables:

curl -s -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"users": 100, "seed": 42, "countries": ["Mexico", "Colombia"]}' | jq .meta

Example metadata response:

{
  "users": 100,
  "goals": 121,
  "transactions": 453
}

Download transaction CSV directly:

curl -s -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -H "Accept: text/csv" \
  -d '{"users": 500, "seed": 7}' \
  -o transactions.csv

Health check:

curl http://localhost:8000/health

{
  "status": "ok",
  "version": "0.2.0"
}

Local REST API limits:

• Rate limit: 10 requests/min per IP

• Maximum: 50,000 users per request

Privacy

The generated datasets are designed for development, testing, demos, experimentation and education without requiring production PII.

Key properties:

• 100% synthetic records

• no row is copied from a real user

• no names, emails, IDs or other direct PII are reproduced from the calibration dataset

• generation is based on aggregate statistical distributions

• synthetic tables preserve realistic relationships between users, goals and transactions

Development

pip install -e ".[dev]"
pytest

MCP registry metadata

This repository includes server.json for MCP registry discovery.

Current server identity:

io.github.jmendozapuche/latam-fintech-synthetic-data

The registered remote MCP endpoint is:

https://mcp.apify.com?tools=active_yardstick/latam-synth

Changelog

v0.2

• lognormal mixture (KS=0.032)

• snap to round values (69.5% on grid)

• coherent temporal trajectories per goal

• 100% of transactions within the [created_at, deadline] window

• FastAPI API

• Apify Actor

• MCP exposure through the hosted Apify MCP Server