# Apps

import Screenshot from "@docs/Screenshot.astro"
import SurfaceTabs from "@docs/SurfaceTabs.astro"
import AskRen from "@docs/AskRen.astro"

An app connects Ren to a service like Gmail, Linear, HubSpot, or Shopify. For example, Gmail lets Ren read, summarize, and draft email.

In the API and CLI, an app is a blueprint with `kind: app`.

## How apps work

An app usually provides tools through an MCP server and can include [skills](/docs/concepts/skills/) that explain how to use those tools. Connect the account or key the app needs. An app's skills are listed with the app, not under **Marketplace → Skills**.

Add an app to a [project](/docs/concepts/projects/) to make it available in every chat. Projects in the same space reuse the connected account. See [Connect an account](#connect-an-account) for credential storage.

Apps provide tools, while [channels](/docs/channels/) receive requests and deliver replies. For example, the Linear app reads and updates issues, and the Linear channel receives issues assigned to Ren.

If a tool has no app but does have an MCP server, add it as a [custom MCP](/docs/concepts/custom-mcps/).

## Find an app

<SurfaceTabs>
<Fragment slot="app">

Open **Marketplace → Apps** to browse or search by name. Select an app to see the MCPs and skills it adds, the publisher, and links to its documentation.

<Screenshot
  shot="apps/marketplace"
  alt="Marketplace Apps with an app drawer open, showing its MCPs, skills, and the Add button"
/>

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Is there an app for HubSpot?" />

</Fragment>
</SurfaceTabs>

You can also browse apps without signing in on the public [Blueprints catalog](/blueprints).

## Add an app to a project

<SurfaceTabs>
<Fragment slot="app">

1. Open **Marketplace → Apps** and select the app.
2. Select **Add**, then pick a project.
3. If the app needs an account, sign in or enter its key, then select **Add to** and the project name.

The app's MCPs and skills are attached to the project and ready in its next chat.

<Screenshot
  shot="apps/add-to-project"
  frame="detail"
  alt="An app's Add menu searched down to the Storefront project in the General team"
/>

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Add the Linear app to this project." />

Ren shows a connect card if the app needs an account.

</Fragment>
<Fragment slot="cli">

```sh
ren blueprints add --source linear --target-project-id <project-id>
```

`--source` takes the app's slug. Connect its account afterward with `ren credentials connect`.

</Fragment>
</SurfaceTabs>

## Connect an account

When Ren needs an app that isn't connected, it shows a connect card in the chat. Connecting from the card also adds the app to the project if it isn't there yet.

<SurfaceTabs>
<Fragment slot="app">

1. Select **Connect** on the card in the chat.
2. Sign in to the account you want Ren to use, or enter the key the app asks for.
3. Return to Ren. The card shows **Connected**, and Ren continues.

Some apps, such as Figma, Meta Ads, and Shopify, end sign-in on a page that won't load. That's expected. Copy that page's full address from the browser, paste it into **Paste the address from the sign-in tab** on the card, and select **Finish**.

If another space you belong to has a connection, select **Reuse** to copy it into this space, or select **Add new** to connect a different account.

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Connect my Gmail account." />

Select **Connect** on the card Ren shows and finish signing in. Connect cards only work in the web app, not in channels.

</Fragment>
<Fragment slot="cli">

```sh
ren credentials connect <mcp> --vault-id <vault-id>
```

Use the vault of the project's space (`ren vaults list`).

</Fragment>
</SurfaceTabs>

The connection is saved in the project's space. In your personal space, it's saved in your personal credentials. If your organization already has a connection for the app, Ren uses it, and the connection dialog shows **Connected using organization credentials**. See [Which credential Ren uses](/docs/concepts/credentials/#which-credential-ren-uses).

## Use an app in a chat

Type `@` in the composer and pick the app. The mention tells Ren which app to use for that request:

```text
@Gmail summarize my unread email from today.
```

Mentions are optional. Mention an app to choose between services that can handle the request. If the project doesn't have the app, Ren shows a connect card to add it.

## Remove an app

<SurfaceTabs>
<Fragment slot="app">

1. Open **Marketplace → Apps** and select the app.
2. Select **Add** to open the project list, then select a project with a check mark to remove the app from it.

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Remove the Linear app from this project." />

</Fragment>
</SurfaceTabs>

Removing an app detaches its MCPs and skills from the project. Ren also deletes the app's credentials from the space if no other project in that space still needs them, but credentials at the organization level will stay.

## FAQ

<details>
<summary>Can a space have two accounts for the same app?</summary>

No. Each space holds one connection per app, and connecting again replaces it. To use two accounts, connect one in each space, or one at the organization level and one in the space.

</details>

<details>
<summary>Which account does Ren use when the app is connected in several places?</summary>

In shared spaces, Ren uses the space's connection before the organization's. In your personal space, your personal connection comes first. See [Which credential Ren uses](/docs/concepts/credentials/#which-credential-ren-uses) for the full lookup order.

</details>