> ## Documentation Index
> Fetch the complete documentation index at: https://synthbrew.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Synthbrew agent setup

> Use Synthbrew from MCP-capable agents with @synthbrew/agent.

`@synthbrew/agent` lets MCP-capable agents create Synthbrew projects, validate schema configs, provision generated sources, create source API keys, and return runtime API docs.

## Install

Most MCP clients can launch the package directly with `npx`:

```bash theme={null}
npx -y @synthbrew/agent
```

## Environment variables

```bash theme={null}
SYNTHBREW_API_KEY=sb_api_...
SYNTHBREW_API_URL=https://api.synthbrew.com/api
```

Use a team public API key from **Settings > Team > Public API keys**.

Configure these in your MCP client. When run directly in a terminal, the process stays open and waits for MCP messages over stdio.

## MCP config

```json theme={null}
{
  "mcpServers": {
    "synthbrew": {
      "command": "npx",
      "args": ["-y", "@synthbrew/agent"],
      "env": {
        "SYNTHBREW_API_KEY": "sb_api_...",
        "SYNTHBREW_API_URL": "https://api.synthbrew.com/api"
      }
    }
  }
}
```

For client-specific setup, see:

* [Codex](/ai-tools/codex)
* [Claude Code](/ai-tools/claude-code)
* [Cursor](/ai-tools/cursor)
* [Windsurf](/ai-tools/windsurf)

For local development, set `SYNTHBREW_API_URL` to your local API base:

```bash theme={null}
SYNTHBREW_API_URL=http://localhost:3311/api
```

## Agent workflow

The calling agent drafts the schema itself, then uses Synthbrew tools to validate and provision resources:

1. Draft a canonical Synthbrew `schemaVersionConfig` using `schemaConfigVersion: "v1"` and `formatVersion: 1`.
2. Call `synthbrew_validate_schema_config`.
3. Fix validation errors and validate again.
4. List or create a project.
5. Create a schema.
6. Create and populate a source.
7. Create a source API key.
8. Get runtime docs and return app integration examples.
9. Fetch sample rows when the user wants to inspect generated data or needs realistic example payloads.

<Warning>
  Source API keys beginning with `sb_src_` are runtime secrets. Store them securely and do not commit them to source control.
</Warning>

## Schema config v1

The public agent contract is frozen as `schemaConfigVersion: "v1"`. The schema config payload uses `formatVersion: 1`.

Synthbrew may add optional fields, enum values, generation settings, and metadata fields to v1 without a new version. Synthbrew will not remove fields, rename fields, change existing meanings, or make optional fields required without introducing a new contract version.

Validation requests can include the contract version explicitly:

```json theme={null}
{
  "schemaConfigVersion": "v1",
  "schema": {
    "formatVersion": 1,
    "entities": []
  }
}
```

## Example prompts

Use prompts that describe the product or workflow you are building. The agent will turn the request into a Synthbrew schema, validate it, create the source, and return the details your app needs.

### Existing app schema

Point your coding agent at the schema files your app already uses when you want Synthbrew data that matches your local models:

```text theme={null}
Use Synthbrew MCP to replicate my database schema at /db/models and generate 100,000 rows. Give me the source database credentials and runtime API docs afterward.
```

The agent can inspect the files, translate the models into a Synthbrew schema, validate the config, populate a source, and return the connection details. This is useful for local development, demos, QA, and frontend work where you need realistic sample rows without connecting to production-like customer data.

### SaaS analytics backend

```text theme={null}
Can you generate a Synthbrew schema for a B2B SaaS analytics app with accounts, users, subscriptions, invoices, product events, and support tickets? Generate 100,000 rows, keep the relationships realistic, create the data source, and give me the connection credentials and runtime API docs.
```

This should produce a relational dataset for dashboards such as MRR, churn, activation, event funnels, support volume, and account health.

### Marketplace demo data

```text theme={null}
Use Synthbrew to create a marketplace dataset with sellers, buyers, products, orders, order_items, payouts, reviews, and refunds. Generate enough data for a realistic admin dashboard, create the source, and return the API key plus example queries I can use in my app.
```

This gives frontend and analytics agents a full commerce workflow to build against without wiring a production database.

### CRM and sales pipeline

```text theme={null}
Create a Synthbrew schema for a sales CRM with companies, contacts, deals, activities, notes, tasks, and pipeline stages. Generate 50,000 realistic records across the tables, create a Postgres source, and return everything needed to connect my app to it.
```

This is useful when you want to build lead lists, kanban pipeline views, sales forecasts, activity timelines, and account detail pages.

## Available tools

* `synthbrew_validate_schema_config`
* `synthbrew_list_projects`
* `synthbrew_create_project`
* `synthbrew_list_schemas`
* `synthbrew_create_schema`
* `synthbrew_list_schema_versions`
* `synthbrew_list_sources`
* `synthbrew_create_source`
* `synthbrew_regenerate_source`
* `synthbrew_get_generation_job`
* `synthbrew_list_generation_events`
* `synthbrew_list_source_api_keys`
* `synthbrew_create_source_api_key`
* `synthbrew_get_runtime_docs`
* `synthbrew_get_source_sample_data`

The package does not call Synthbrew's AI schema generator. Your agent authors schemas and uses Synthbrew validation to repair them.