Getting Started

---
name: getting-started
description: Use when a user expresses interest in using the Recast API. They may hit limitations of the MCP tools such as "I need to run a forecast (or optimization) and the MCP can't" or "I want to create a repeatable, deterministic workflow" or they may explicitly ask for help getting set up on the API "I want to use the API", "How do I authenticate the API", "How do I get a PAT for the API", etc. The MCP uses OAuth authentication, but all API calls require a PAT.
---

# Recast Getting Started — Auth & Plugin Setup

Recast has **two independent auth paths**. Don't conflate them — using the wrong
one is the most common source of confusion:

| What you're using | How it authenticates | Needs a PAT? |
|---|---|---|
| **MCP server** — the `recast` tools (`list_clients`, `run_report_tool`, `get_report`, …) | **OAuth** browser sign-in with your Recast account | **No** |
| **API skills** — code the `reporter-api` / `forecaster-api` / `optimizer-api` / `plans-api` skills generate to call the Recast API directly | a **`RECAST_PAT`** in the environment | **Yes** |

Most users only need the MCP server, and it needs **no token to configure** —
just an OAuth sign-in. Only reach for a PAT if you'll run the Python/R scripts
the API skills produce.

## Verify that the user wants to execute code
Many users may not be sure what the MCP can do and what the API skills are for. Additionally, users may be non-technical marketers who may not be comfortable running code. However, some users will be data scientists comfortable executing R or Python code. Confirm either from their stated goals or by asking them if they have a code execution environment and want help writing scripts that hit the API. If not, encourage the MCP use and do not try to set up a PAT for them.

## Getting a PAT (only if you'll run API-skill scripts)

Skip this unless you're running code generated by the `reporter-api`,
`forecaster-api`, `optimizer-api`, or `plans-api` skills — those call the Recast API directly
and read a personal access token from the `RECAST_PAT` environment variable. 

1. Log in to the Recast app at https://app.getrecast.com.
2. Open the **account menu** in the top nav bar — the dropdown labeled with your email address.
3. Click **"Generate API Token"**.
4. Confirm the dialog. **Warning:** this revokes any existing API token for the account — if a token is already in use elsewhere (scripts, another machine, Claude Desktop), reuse that token instead of generating a new one.
5. The token is shown **exactly once** in a modal — copy it immediately. It cannot be viewed again, only regenerated.

## Configuring RECAST_PAT (for the API skills)

Encourage users to set a `RECAST_PAT` environment variable following the best practices of whatever language they're using. For example, in Python, you can set it in the shell before running a script:

```bash
export RECAST_PAT="your-token-here"
```

In R, this is typically done in the `.Renviron` file:

```
RECAST_PAT=your-token-here
```

Encourage standard practices for storing secrets, such as using environment variables or secure vaults, and never hardcoding the token in scripts or committing them to version control.

Additionally, if they want Claude Code to see the token, they can add it to `~/.claude/settings.json` under the top-level `env` key:

```json
{
  "env": {
    "RECAST_PAT": "<your-pat>"
  }
}
```
Doing this will make it so Claude can execute the API-skill scripts when running Claude Code anywhere on your machine.