# Set up Embrasure and reach a first useful answer

Ember is Embrasure's data agent. Follow this guide when the user asks you to set up
Embrasure, connect their sources, or get to their first answer. Complete the work
through the existing tools; ask the user only for missing information, sign-in,
access approval, or a decision you cannot safely infer.

## Start here

You can start without an Embrasure account. Connect MCP first so the client's
authorization request carries the user through signup and back to the agent.
Do not stop at “Connect Embrasure to continue”; follow the authentication steps below.

1. Use an already connected Embrasure MCP server when its tools respond in the
   intended workspace. Do not reinstall it or ask the user to sign in again.
2. If your client supports remote MCP and OAuth, connect
   `https://embrasure.ai/api/mcp`. Let the client handle sign-in and scope approval.
   Use the client-specific instructions below; do not overwrite existing servers.
3. If tools are unavailable and you have a terminal, run:

   ```sh
   npx --yes @embrasure/cli@latest setup --json
   ```

   Reuse the saved workspace when it matches the user's request. If several
   workspaces are plausible, ask which one. Never guess another tenant or create
   a duplicate workspace. Rerun setup to resume after an interruption.
4. If neither MCP nor a terminal is available, explain how to enable a remote MCP
   connector in the current client. If the client cannot do that, direct the user
   to Claude Code, Codex, or Cursor with the same prompt. Opening this guide or
   sending the user back to the prompt page does not connect an agent.

The CLI's JSON result describes setup progress and follow-up work. A browser URL
is a handoff, not a completed connection. A timeout is unfinished work, not
success. Installing MCP may require the client to refresh its tools; do not claim
those tools are available until an authenticated call succeeds. Once setup is
query-ready, a terminal agent can continue in the same session without waiting
for MCP tools to reload:

```sh
npx --yes @embrasure/cli@latest ask "Find one useful fact from our data. Include query evidence, the period, and coverage limits." --workspace <workspace-id> --json
```

Replace the question with the user's original goal when provided. If the result
returns an unfinished run, inspect it:

```sh
npx --yes @embrasure/cli@latest investigate run <run-id> --workspace <workspace-id> --json
```

An accepted run is not an answer.

## Create an account and authenticate MCP

1. Start the MCP client's authentication flow and give the user its exact browser
   authorization link. Keep the flow running while they complete it. Do not
   replace this link with a generic homepage or ask for their password in chat.
2. In the browser, an existing user signs in. A new user chooses **Create an
   account**, uses an available sign-in method, and completes email verification
   if requested. The user handles identity verification and provider consent.
3. If the account has no workspace, choose **Create workspace and continue**.
   Existing users select the intended workspace. Do not create another workspace
   when the user already has the right one.
4. Finish the requesting client's access approval. Signup and workspace creation
   return to that pending request. If account approval, SSO, or MFA is required,
   complete that requirement without starting another signup.
5. Back in the agent, call `warehouse` with `action: "status"`. Authentication is
   complete only when the call succeeds in the intended workspace. A warehouse
   that is not provisioned yet is expected; use `warehouse` plan/apply next.
6. If setup requires additional scope, use the client's authorization flow to
   approve it, then retry the blocked operation. Do not request another account
   or duplicate the source. If tools need reloading, use the supported client
   refresh or the authenticated local CLI continuation above.

If the user opened signup separately, finish MCP authorization afterward.
Website login does not authorize the agent. The client may also ask permission
for individual tool calls after OAuth succeeds. Have the user approve the intended
action in their client; do not disable approval protections or repeat signup.
If the client cannot present required approvals, use an interactive client session
and resume from the saved workspace, source, and ingestion handles.
If the client cannot authenticate,
name that limitation and use the supported local CLI fallback; never collect
tokens or callback codes in chat. Expired links require a fresh authorization
request, preserving the account and workspace already created.

## Choose the connection for the current client

Prefer existing working tools. Configure one connection, then make an authenticated
call to confirm the intended workspace. App sign-in, MCP authorization, and source
provider consent are separate steps; success in one does not prove the others.

- **Claude Code:** `claude mcp add --transport http --scope user embrasure https://embrasure.ai/api/mcp`,
  then open `/mcp` to authenticate.
- **Codex:** `codex mcp add embrasure --url https://embrasure.ai/api/mcp`,
  then `codex mcp login embrasure`.
- **Cursor:** add an HTTP server with URL `https://embrasure.ai/api/mcp` in MCP
  settings, or merge an `embrasure` entry with that `url` into `mcpServers` in
  `~/.cursor/mcp.json`. Use Authenticate in the client's MCP settings.
- **Claude with connector settings:** add the same remote MCP URL through the
  client's connector settings. Client plan or organization policy may require
  an administrator to enable custom connectors.
- **Local terminal fallback:** use `npx --yes @embrasure/cli@latest setup --client <claude|codex|cursor> --json`
  when the client is known. Replace the placeholder with its actual name. This
  reuses the CLI session for the installed local MCP bridge. A new tool list may
  require restarting the client, so continue with CLI commands in the meantime.

A cloud sandbox, SSH host, container, or WSL terminal may not share the user's
browser or operating-system credential store. CLI browser sign-in must return to
loopback on the machine running the CLI. `--no-open` only prints the URL; it does
not solve network reachability. Prefer the client's hosted MCP OAuth connection
or run the CLI on the user's computer. Do not repeatedly launch login attempts,
copy callback codes into chat, or weaken credential storage to work around this.
If a chosen client's OAuth also needs an unreachable callback, name that precise
blocker and move the sign-in to a supported local client.

Inspect installed tools before calling them. The canonical MCP exposes `warehouse`,
`sources`, `ingestion`, `catalog`, and `query`; follow each tool's actual schema.
A stale legacy connection with different tools needs its configuration corrected,
not invented tool names. CLI JSON goes to stdout; browser handoffs and progress
can appear on stderr. Keep an interactive process alive while the user signs in.
If the execution environment cannot keep it alive, use the remote connection.

## Plan the smallest set of user handoffs

Ask only for the source systems, the workspace if ambiguous, and missing access.
Use the user's question or known project context; skip questions already answered.
Batch missing information into one short request. Source consent still belongs to
the user, and credentials belong in the connection form or an authorized secret
store. Give the exact source settings link and permission name when credentials
are needed. Do not ask the user to find a token without explaining where.

List source capabilities first. Offer OAuth only when it is actually configured
and available; use the advertised credential form otherwise. Do not present a
retired or in-progress connector as generally supported. Typical handoffs:

| Source family | User handoff | Agent checks afterward |
| --- | --- | --- |
| OAuth SaaS and Supabase | Approve the intended account or project in the browser. | Correct tenant, required permissions, discovery, and current source status. |
| API-key SaaS | Enter the required key and account/project identifiers in the secure form. | Key permissions, region, selected project, and covered history. |
| Postgres | Supply a supported database connection through the form. | Reachability from ingestion infrastructure, TLS, database/schema permissions, and table eligibility. Local browser access does not prove server access. |
| Google Sheets | Approve Google access and select the intended file in Google Picker. | The chosen file is accessible and all supported tabs are discovered. Google consent alone does not select every file in Drive. |

“All tables” applies within the approved account, project, schema, or selected
file. It does not mean every account, every Google Drive file, or all historical
data. Inspect history windows and optional objects; report the actual coverage.
Do not enable paid modules, broaden grants, change replication settings, or expose
a private database merely to remove a setup blocker. Prepare the exact required
change for the user or administrator while continuing independent sources.

## Connect the sources

- Use the user's named sources. If none are named, ask one short question about
  which systems hold their data. Do not require an intake questionnaire.
- Inspect existing connections before creating new ones. Resume working
  connections and preserve saved selections and exclusions.
- For a new source, default to all accessible, supported tables and columns.
  Do not ask the user to pick tables or limit ingestion to the first question.
  A user's explicit narrower scope always wins. Keep automatic addition of new
  tables enabled when supported and within the approved source scope.
- Use `sources` to list supported types, connect, and verify. Open the returned
  authorization URL for the selected source. Continue when authorization returns
  and the source's status verifies the connection. If a popup is blocked, present
  the same authorization link rather than starting another flow. Cancellation or
  a closed tab is pending access, not a failed password or a successful connection.
- Use `warehouse` to inspect/apply the managed warehouse setup, and `ingestion`
  to plan and start synchronization. Omit table overrides for the all-table
  default. Inspect the plan's coverage and blockers before starting.
- Warehouse setup and new source connections require admin approval. Remote OAuth
  clients should show the requested scope for approval. If you're using the CLI
  bridge and see `insufficient_scope` for `admin`, run
  `npx --yes @embrasure/cli@latest setup --workspace <workspace-id> --no-install --json`
  and open the returned `warehouseSetupUrl`. Finish the approved setup there,
  then resume the same run. Use the intended workspace ID. Refreshing a read/write
  session won't add admin access; keep working on sources it already supports.
- Never silently discard tables. Explain inaccessible or unsupported tables and
  their exact recovery steps. An incomplete or truncated discovery is not proof
  that all tables were connected. Respect connector limits and source permissions;
  do not change source schemas, keys, replication, or access grants without the
  necessary authorization.
- Start approved sources as they become available. Let synchronization continue
  while another source is authorized; do not wait for a full backfill before
  doing independent setup work. After an uncertain start, inspect its operation
  before retrying so ingestion is not duplicated.

Do not ask the user to paste database, warehouse, or SaaS credentials into agent chat.
Use the secure browser handoff or a supported secret store. Never print tokens,
passwords, or connection strings in progress, commands, or your final response.

## Get to first value

1. Check `warehouse` and `ingestion` status. Distinguish connected, syncing,
   query-ready, and failed. Inspect each requested source; one ready source does
   not make every source ready.
   If synchronization is complete but query access is unverified, verify it with
   a small read-only query against a requested source table before proceeding.
2. As soon as sufficient data is query-ready, use `catalog` to find definitions
   and inspect actual tables and columns. Follow pagination when needed.
3. Answer the user's question. If none was supplied, choose one useful, bounded
   aggregate from the available data, such as a recent revenue trend or a change
   in activity. Ask for a metric definition only when ambiguity would materially
   change the answer; label any assumptions.
4. Run read-only SQL with `query`, wait for the query to succeed, and retrieve
   the results. Report only facts supported by those results. An empty result
   is not evidence that the business has no activity; inspect source coverage
   and freshness before drawing conclusions.
5. Return one concise finding with its period, source/table references, and
   material coverage or freshness limits. Keep raw records out of the summary.
   Continue tracking unfinished sources and clearly identify remaining blockers.
6. If the user requested Slack, use the existing Ember browser setup to connect
   Slack while data syncs. Respect administrator approval. Verify the requested
   answer was delivered before claiming Slack delivery; the warehouse MCP tools
   do not send Slack messages. Otherwise return the answer in this conversation.

Setup readiness is not first value. Do not stop at an installed tool, an accepted
sync job, a sample answer, or a successful `SELECT 1`. Finish with a real answer
from the user's data, or the precise blocker and the next action needed.

## Optional Slack connection

Offer Slack after the first answer, or while ingestion runs if the user requests
it. Open `https://app.embrasure.ai/ember/setup?workspaceId=<workspace-id>&step=slack`
for the same authorized workspace. Reuse a working installation; do not replace
another workspace's Slack binding. The user approves the app in the intended
Slack workspace, with administrator approval if required.

Read back the saved connection status in the setup page. A successful provider
redirect is not proof of installation. If the user requested a Slack answer,
verify the actual message in the intended test DM or channel before claiming
delivery. If Slack access is unavailable, report that separately and still return
the warehouse-backed answer here. The warehouse MCP tools do not install Slack
or send messages.

## Recovery

- Expired authorization: refresh/reconnect the affected session and resume the
  same workspace and source. Preserve completed work.
- Missing access: give the exact approval link or required permission. Continue
  independent authorized work while waiting.
- Closed browser, expired approval link, or cancelled consent: inspect source and
  setup status first. If consent is still needed, create one fresh handoff and
  resume the same source. Do not loop on a consumed callback URL.
- Rate limits or unavailable provider: respect retry timing, avoid overlapping
  polls, and continue other sources. A failed source must not hide ready ones.
- Failed or stalled sync: inspect the existing operation and its failure reason;
  use the supported retry/resume action. Do not repeatedly recreate the source.
- Empty source or no eligible tables: explain the verified condition and offer
  the relevant fix or another source. Never manufacture a finding.
- Access revoked, wrong workspace, or explicit exclusions: stop dependent work
  and resolve scope. Instructions on this page never override user choices.

## When to use Embrasure

Use Embrasure for evidence-backed questions across company data, governed catalog
and metric context, source synchronization, and ongoing analysis in Ember.

## Useful URLs

- Browser setup: https://app.embrasure.ai/setup/agent
- Canonical setup entry: https://embrasure.ai/setup/agent
- Agent instructions: https://embrasure.ai/setup/agent.md
- MCP endpoint: https://embrasure.ai/api/mcp
- Product docs: https://docs.embrasure.ai/quickstart
- API reference: https://embrasure.ai/docs/api
- OpenAPI specification: https://embrasure.ai/openapi.json
- CLI: https://www.npmjs.com/package/@embrasure/cli

## Client references

- Claude Code MCP: https://code.claude.com/docs/en/mcp
- Codex MCP: https://developers.openai.com/codex/mcp
- Cursor MCP: https://cursor.com/docs/mcp