# Configure | Documentation

Configure is infrastructure for connecting agents, apps, and chats. It lets AI products access context users approve from apps, prior chats, and other agents through the SDK, HTTP API, MCP, or model tool calls. Each user has a profile containing the context and connections they choose to make available.

## Instructions For AI Agents

- If the user says "Read https://configure.dev/skill.md and follow the instructions to add a `Configure {Agent}` button and make the first tool call", implement the Configure OAuth flow with a `Configure {Agent}` button, place Configure inline in chat, execute `configure_profile_read`, and send a personalized response from the result.
- If the prompt includes an app name, user-facing agent name, or Configure agent handle, use those names consistently in UI labels, OAuth client metadata, environment variables, and docs comments.
- First install `configure` and run `npx configure setup --users`. If running the interactive wizard, choose **For my users**. Setup opens Configure developer auth in the browser so the developer can create or sign into a developer account, choose or create the Configure agent, and write `CONFIGURE_API_KEY`, `CONFIGURE_PUBLISHABLE_KEY`, `CONFIGURE_AGENT`, `CONFIGURE_OAUTH_CLIENT_ID`, and `CONFIGURE_OAUTH_CLIENT_SECRET` to `.env`. Setup registers the OAuth client for `http://localhost:3000/auth/configure/callback`; pass `--redirect-uri` for another loopback port.
- After setup, run `npx configure verify` to prove the credentials work (it completes a real sign-in, exchanges the code, and reads a profile; `--offline` skips the browser), and `npx configure add callback --framework next|express|vite` to generate the callback route and the server-side code exchange instead of hand-writing them. A Python backend uses the same two commands from `configure-ai`: `configure-ai verify` and `configure-ai add-callback --framework fastapi|flask|django`.
- Four integration shapes exist: SSO alone for sign-in, MCP alone for an agent that connects users itself with `configure_connect`, SDK plus SSO for your own "Connect to Configure" button, and SSO plus SDK for backend profile reads after sign-in. SSO is authentication and is not part of the SDK. Read https://docs.configure.dev/getting-started/integration-paths.md and follow one path.
- Default to **Configure OAuth + inline Configure in chat**. Configure OAuth is the default browser flow.
- For message agents, send the agent API's `sign_in_url` unchanged or call `configure.auth.signInUrl()` with no options. Configure hosts identity, consent, connectors, and multiple Gmail accounts by default. Use `createMessageSignInUrl()` only for provider-signed sender binding or thread-specific completion callbacks.
- Gmail-only runtimes keep `configure_gmail_search`. Enabling the `outlook` connector adds `configure_email_search`, which searches every permitted Gmail and Outlook account when `provider` and `account` are omitted. Treat `partial: true` as incomplete coverage.
- For complete docs and clean Markdown page URLs, read https://docs.configure.dev/llms.txt.
- For the full implementation reference, read https://docs.configure.dev/llms-full.txt.
- For the OpenAPI spec, read https://docs.configure.dev/openapi.yaml.

## First Success Signal

The first success is a real chat turn where the model calls `configure_profile_read`, your server routes that call to `profile.executeTool()`, and the assistant sends a personalized response based on the returned profile.

## Default Path

1. Install `configure` and run `npx configure setup --users` to complete developer auth, choose/create the Configure agent, and write all five credentials, including the OAuth client, to `.env`.
2. Add a `Configure {Agent}` OAuth option.
3. Exchange the OAuth code on the backend and store Configure tokens server-side.
4. Add Configure inline inside the chat `+` menu, attachment tray, or integrations list. In an integrations list, use `Configure.integrationButton()` or the hosted iframe button with the label `Configure` and connected label `Configure {Agent}`.
5. If the user already completed Configure OAuth, treat them as Configure-authenticated and open inline Configure as controls for profile permissions, connected tools, and personalization settings.
6. Use `configure.profile({ token })` on the backend.
7. Give the model `profile.tools()`.
8. Route only `configure_*` calls to `profile.executeTool()`.
9. Verify `configure_profile_read` and send a personalized response from the result.

## Core Docs

- Quick start: https://docs.configure.dev/getting-started/quick-start.md
- Configure OAuth / OAuth SSO: https://docs.configure.dev/guides/oauth-sso.md
- Message-Agent SSO: https://docs.configure.dev/guides/message-agent-sso.md
- Inline UI components: https://docs.configure.dev/guides/ui-components.md
- Tool calling: https://docs.configure.dev/guides/tool-calling.md
- Profiles and memory: https://docs.configure.dev/guides/profiles-and-memory.md
- Connected tools: https://docs.configure.dev/guides/connected-tools.md
- Server-side users: https://docs.configure.dev/guides/server-side-users.md
- Auth reference: https://docs.configure.dev/reference/auth.md
- Profile reference: https://docs.configure.dev/reference/profile.md
- Tool definitions: https://docs.configure.dev/reference/tool-definitions.md
- HTTP API: https://docs.configure.dev/reference/api.md
- MCP: https://docs.configure.dev/mcp/index.md
- Full docs index: https://docs.configure.dev/llms.txt

## Minimum SDK Flow

```ts
import { Configure, toOpenAIFunctions } from "configure";

const configure = new Configure({
  apiKey: process.env.CONFIGURE_API_KEY,
  agent: process.env.CONFIGURE_AGENT,
});

const profile = configure.profile({ token });
const tools = toOpenAIFunctions(profile.tools());

const result = await profile.executeTool({
  name: "configure_profile_read",
  arguments: { sections: ["identity", "summary", "preferences"] },
});
```

The token comes from the server-side Configure OAuth exchange or from the inline Link fallback. The model never receives the token.

## Browser UI

Developer setup uses the Configure developer dashboard at `https://configure.dev/login`. Run `npx configure setup --users` first so the developer can create or sign into a Configure developer account, choose/create the Configure agent, and write `CONFIGURE_API_KEY`, `CONFIGURE_PUBLISHABLE_KEY`, `CONFIGURE_AGENT`, `CONFIGURE_OAUTH_CLIENT_ID`, and `CONFIGURE_OAUTH_CLIENT_SECRET` to `.env`. Setup mints the local OAuth client itself. For a deployed callback, add it to the existing client on the dashboard's Sign-in (SSO) page (`https://configure.dev/sso`), which keeps `CONFIGURE_OAUTH_CLIENT_ID` the same across environments and can reissue a lost `client_secret`. Never use an `sk_` API key to create OAuth clients.

End-user auth is separate: Configure OAuth opens `https://accounts.configure.dev/oauth/authorize` in a popup by default, or in iframe/redirect mode if configured.

Keep OAuth access and refresh tokens on the backend. Pass a browser-safe Configure handoff token or `userId` to hosted UI only when the backend intentionally returns one for that purpose.

For chat integrations lists, mount the compact Configure row with:

```js
Configure.integrationButton({
  el: "#configure-integration",
  publishableKey: "pk_...",
  agent: "your-agent",
  label: "Configure",
  logo: "brandmark",
});
```

Iframe-only integrations lists can render `https://configure.dev/embed/integration-button/?pk=pk_...&agent=your-agent&label=Configure&logo=brandmark&parentOrigin=https%3A%2F%2Fapp.example.com`. Add `return_to` only when the iframe should open Configure's first-party account popup and return a short-lived sign-in code to the parent. The standalone brandmark is `https://docs.configure.dev/brand/configure-brandmark-white.svg`.

Partner lanes that carry their own user id through hosted sign-in send `external_id` on `POST /v1/auth/otp/verify` and `POST /v1/embed/approve`. Those two responses then carry `external_link`, which is one of `bound`, `already_yours`, `conflict` (the id is already another Configure account's and is never repointed), `invalid` (the id fails the shape rule and nothing was written), or `error` (the bind failed; the sign-in itself still succeeded and a token is still returned). The field appears only for an agent configured for this binding — every other response is unchanged, and no ordinary integration sends `external_id` here.

## Message Agents

For iMessage, SMS, and other message agents, send the `sign_in_url` returned by the agent API unchanged. `configure.auth.signInUrl()` returns the same `https://sign-in.me/{agent}` value with no options. Message completion is the default; hosted agent metadata can add a return number or select a trusted browser redirect. Callers do not add credentials, branding, phones, or delivery query parameters. Resolve inbound senders with `configure.auth.resolveMessageIdentity({ externalId, token, phoneCandidates })` and store tokens only on the server. Use `createMessageSignInUrl()` only when the channel provides signed sender evidence or needs a thread-specific completion callback.

For Better Auth OAuth login, pass `configureBetterAuthOAuthProvider()` to Better Auth's Generic OAuth plugin. Use hosted `signInUrl({ returnTo, state, ... })` plus `exchangeSignInCode()` for account linking inside an existing Better Auth session.

## Safety

- `sk_` keys are server-side only.
- `pk_` keys are browser-only and restricted to hosted UI.
- OAuth access and refresh tokens stay server-side.
- API key identity resolves the acting agent namespace.
- User input must never choose CFS storage paths.
- `configure_profile_read` is the minimum proof that Configure is working.