# Hosted MCP - SynthForge Docs

> Connect agents to SynthForge over the Model Context Protocol (Streamable HTTP). Forge schemas from natural language, generate multi-table datasets, wait for jobs, and download results with an API key.

- Canonical URL: https://synthforge.io/docs/mcp
- Open beta overview: https://synthforge.io/mcp
- MCP endpoint (prod): https://mcp.synthforge.io/mcp
- Server card: https://synthforge.io/.well-known/mcp/server-card.json
- API keys guide: https://synthforge.io/docs/api-keys.md
- Auth for agents: https://synthforge.io/auth.md

## Credits for agents

MCP and API-key jobs use **product credits** (1 credit per forge / generate / ML job).

- **First API key:** minting your first key under Settings → API keys automatically grants **10 free credits** so you can complete several agent loops without emailing support.
- **Web app:** interactive sessions stay free and do not spend credits.
- **Open beta (extra grants):** through **August 31, 2026**, request more credits from **support@synthforge.io** (same address as your app account). Overview: https://synthforge.io/mcp.md

## Endpoint

| Environment | Base URL | API |
|---|---|---|
| Production | `https://mcp.synthforge.io/mcp` | `https://api.synthforge.io` |
| Development | `https://mcp-dev.synthforge.io/mcp` | `https://api-dev.synthforge.io` |

Transport: **Streamable HTTP**. Unauthenticated requests return **401** with `WWW-Authenticate: Bearer realm="synthforge-mcp"`.

Server card: `GET https://mcp.synthforge.io/.well-known/mcp/server-card.json` (or the apex card at https://synthforge.io/.well-known/mcp/server-card.json).

## Authentication

1. Sign in at https://app.synthforge.io
2. Create a personal API key under **Settings → API keys** (`sfk_live_…` on prod). Your first key includes 10 credits.
3. Send `Authorization: Bearer sfk_live_…` on every MCP request

Check balance anytime with the MCP tool `get_credits` or Settings → API credits.

## Install by host (Layer 3.1)

Constants for every host:

| Item | Value |
|------|--------|
| MCP URL | `https://mcp.synthforge.io/mcp` |
| Auth | `Authorization: Bearer sfk_live_YOUR_KEY` |
| Transport | Streamable HTTP |

### Cursor

1. Settings → MCP (or open your Cursor MCP config file).
2. Add a remote server entry:

```json
{
  "mcpServers": {
    "synthforge": {
      "url": "https://mcp.synthforge.io/mcp",
      "headers": {
        "Authorization": "Bearer sfk_live_YOUR_KEY"
      }
    }
  }
}
```

3. Restart MCP / reload Cursor. Confirm tools include `description_to_dataset` and `get_credits`.

### Claude Desktop

If your Claude Desktop build supports remote Streamable HTTP MCP servers, add the same URL + Bearer header in its MCP server settings (UI labels vary by version). If the build only supports stdio local servers, use the monorepo stdio entry for local dev (`pnpm --filter @synthforgeio/mcp stdio` with env pointing at the API), or use Cursor / another Streamable HTTP host against prod.

### Claude Code / CLI hosts

Configure the host's MCP remote server list with:

- URL: `https://mcp.synthforge.io/mcp`
- Header: `Authorization: Bearer sfk_live_YOUR_KEY`

Then call `description_to_dataset` from the agent session.

### Generic / other agents

Any client that can open Streamable HTTP MCP and send a Bearer header works. Server card (discovery):

```text
https://mcp.synthforge.io/.well-known/mcp/server-card.json
```

## Try this prompt

```text
Use SynthForge description_to_dataset to create a multi-table ecommerce schema
(customers, orders, order_items) with foreign keys, ~200 customers, 1-4 order
items per order via relationship_counts, formats csv, then give me the Download link.
```

## Core tools

| Tool | Purpose |
|---|---|
| `whoami` | Account for the API key |
| `get_credits` | Credit balance, costs, and API-key vs free-session policy |
| `get_quota` | Effective plan limits + credit_balance (diagnose 429s) |
| `description_to_dataset` | North star: forge → generate → wait → download package |
| `forge_schema` | Description → schema only |
| `generate_dataset` | Existing schema + row counts → download package |
| `wait_schema_job` / `wait_dataset` | Poll until terminal; push progress when client sends `progressToken` |
| `get_schema_job_status` / `get_dataset_status` | Single-poll status |
| `get_download_url` | Refresh download package for a completed dataset |
| `cancel_dataset` | Abort an in-flight generation job |
| `list_schemas` / `get_schema` | List and inspect schemas |
| `list_datasets` / related helpers | Multi-step generation workflows |

Prefer `description_to_dataset` with `default_rows` when table names are unknown. Completed tools return a **Download:** URL and may attach a ZIP when the host supports it.

## Agent tips

- For org charts and similar hierarchies, prefer a separate link table (for example `reporting_lines`) over a self-referencing foreign key.
- Re-use the integer `seed` returned on a dataset with the same schema and counts for reproducible non-UUID columns.
- If you hit insufficient credits, call `get_credits` or generate interactively in the free web app.
- If the schema is rejected, read the error detail, adjust the description, and try again.
- Full REST surface: https://api.synthforge.io/openapi.json

## Discovery

- SEP-1649 server card: https://synthforge.io/.well-known/mcp/server-card.json
- Legacy mirror: https://synthforge.io/.well-known/mcp.json
- Agent manifest: https://synthforge.io/.well-known/agent.json