> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alpha.new/llms.txt
> Use this file to discover all available pages before exploring further.

# Use integrations in your app

> Call your connected apps and MCP servers from the code the agent writes, in the Preview, in published apps and in exported copies.

Every session has a key that lets the app it builds call the apps and remote MCP servers you connected, with no app token anywhere in your code. The agent uses it for you; you only handle it yourself when you run an exported copy somewhere else. To connect something first, see [Connect an app](https://docs.alpha.new/integrations/connect-apps.md) or [MCP servers](https://docs.alpha.new/integrations/mcp-servers.md). For your own API keys, use [Secrets](https://docs.alpha.new/secrets.md).

![The top of a session's Secrets tab. Under the heading This session, with a lock icon, a card titled This session's key reads: Set for you in every shell and on every deployment. For an exported copy, put these two in its .env. Rotating invalidates every copy; deployments need a redeploy. Below it are two rows in monospace: FORGE\_TOOLS\_URL with https://alpha.new/api/tools/v1, and FORGE\_TOOLS\_API\_KEY shown as a row of dots, each with a copy icon at the right. Under the rows are three buttons: Reveal, Copy .env lines and Rotate.](https://mintcdn.com/lyzr-15a99e0f/ObBpayiae_4aNgzN/images/integrations/tools-key-card-masked.png?fit=max\&auto=format\&n=ObBpayiae_4aNgzN\&q=85\&s=0368ac334472cfc637f0f95c2543b3f4)

The key sits at the top of the session's Secrets tab, masked until you click Reveal.

> [!NOTE]
>
> If the card shows "tools gateway is disabled" instead of the key, the tools gateway isn't turned on for your Alpha. Ask your administrator.

## How does your app reach your connections?

Your app reads two variables, `FORGE_TOOLS_URL` and `FORGE_TOOLS_API_KEY`, and sends every call to Alpha's tools gateway. The gateway holds your sign-ins, attaches the right one and calls the app. Your app never sees the app's own token, so there is nothing to leak beyond the key itself.

```mermaid theme={"system"}
flowchart LR
  P[App in the Preview] --> G
  D[Published app] --> G
  E[Exported copy] --> G
  G[Alpha tools gateway] -->|your sign-in| C[Connected apps]
  G -->|your sign-in| M[Remote MCP servers]
  classDef focus stroke:#1A54F0,stroke-width:1.5px;
  class G focus
```

The same code runs in all three places. Only the way the variables arrive changes:

| Where the app runs | How it gets the two variables |
| - | - |
| The session's machine: the [Preview](https://docs.alpha.new/workspace/preview.md), the [Shell](https://docs.alpha.new/workspace/shell.md) and every command the agent runs | Set for you. Nothing to do. |
| A [published app](https://docs.alpha.new/publish/publish-your-app.md) | Set for you on every publish. The log reads "tools: this session's Alpha tools key is set on the deployment". |
| An exported copy you run elsewhere | You paste them into its `.env`. See [Run your app outside Alpha](#run-your-app-outside-alpha). |

## Find this session's key

The key card appears in two places. Both show the same key for the open session.

**Secrets tab**

In a session, open the workspace's **+** menu and choose **Secrets**. The card **This session's key** sits at the top, under **This session**. The tab is for the session's owner Owner only. Viewers of a [shared session](https://docs.alpha.new/sharing.md) don't get it.

**Integrations**

Open **Integrations** in the sidebar, then **Connectors → Built in → Alpha tools**. The panel explains the built-in, shows the same card, and lists both variables under **What the agent gets**. With no session open, the card reads "Open a session to see the key its app and agents use."

| Control | What it does |
| - | - |
| Copy icon on a row | Copies that value, shown or not. The tooltips read "Copy the URL" and "Copy the key". |
| **Reveal** / **Hide** | Shows the start and end of the key, or masks it again. |
| **Copy .env lines** | Copies both variables as two `.env` lines. The button reads **Copied** afterwards. |
| **Rotate** | Replaces the key at once, with no confirmation. The new key is shown and the button reads **Rotated ✓** for a moment. See [Rotate the key](#rotate-the-key). |

## Run your app outside Alpha

When you download or push an app and run it on your own machine or host, it no longer gets the variables for free. Give it the two lines once.

**1. Copy the lines**

On the key card, click **Copy .env lines**.

**2. Paste them into the app's .env**

Add them to the `.env` file the app loads at startup. The address points at your Alpha, so the place you run the app must be able to reach it.

```env theme={"system"}
FORGE_TOOLS_URL=https://<your Alpha address>/api/tools/v1
FORGE_TOOLS_API_KEY=fka_XXXXXXXXXXXXXXXX.XXXXXXXX
```

**3. Keep the key out of your repository**

Alpha tells the agent never to write the key into a file. Instead, the agent lists both variables in `.env.example` with empty values, so the code says what it needs without carrying the key. Keep `.env` out of version control.

## Rotate the key

**Rotate** issues a new key for this session and retires the old one at once. Every copy of the old key fails its next call, wherever it lives. It can't be undone, and the old key never works again.

> [!WARNING]
>
> Rotate as soon as the key leaks: pasted into a message, committed to a repository or sent to someone. Anyone holding it can call every app and MCP server you connected until you do.

| Where the old key was | What happens after **Rotate** |
| - | - |
| The session's machine | Alpha writes the new key into the machine and refreshes the agent's tools. If the agent is mid-turn, the refresh waits until the turn ends. A server already running in the Preview keeps the old key until it restarts. |
| A published app | Its calls fail until you [republish it](https://docs.alpha.new/publish/manage.md#republish-your-changes). Republishing sets the new key. |
| An exported copy | Its calls fail until you copy the new lines into its `.env`. |
| Your other sessions | Unaffected. Each session has its own key. |

Deleting the session retires its key the same way.

## How the agent calls your tools

You don't write any of this by hand. Ask for the feature in plain words and name the connection.

Try this

```text theme={"system"}
When someone books a class, post the booking to our #bookings channel using my connected Slack.
```

Alpha will:

1. Check which tools you've connected. If Slack isn't one of them, it posts a card in the transcript with a button to [connect it](https://docs.alpha.new/integrations/connect-apps.md).
2. Read the gateway's contract and find the Slack tool it needs.
3. Write code that reads `FORGE_TOOLS_URL` and `FORGE_TOOLS_API_KEY` from the environment and calls that tool.
4. Name both variables, empty, in `.env.example`.

The contract is two calls. `GET /tools` lists every tool you've connected, each with an id that names its connection and the parameters it takes. `POST /tools/{id}/execute` runs one, with the arguments in the body.

```js theme={"system"}
const base = process.env.FORGE_TOOLS_URL;
const headers = {
  Authorization: `Bearer ${process.env.FORGE_TOOLS_API_KEY}`,
  "Content-Type": "application/json",
};

export const listTools = () => fetch(`${base}/tools`, { headers }).then((r) => r.json());

export const executeTool = (id, args = {}) =>
  fetch(`${base}/tools/${encodeURIComponent(id)}/execute`, {
    method: "POST",
    headers,
    body: JSON.stringify({ arguments: args }),
  }).then((r) => r.json());
```

Every reply has the same shape, whichever app answered: `{"ok": true, "data": …}` or `{"ok": false, "error": {"kind": …, "message": …}}`. An app's failure can arrive with HTTP status 200, so the code checks `ok`, not the status.

| `error.kind` | Means | What to do |
| - | - | - |
| `auth` | The key is missing, wrong or rotated | Republish, or copy the new lines into an exported copy's `.env` |
| `connection` | You removed that connection, or it needs a new sign-in | Reconnect it in **Integrations**. Retrying won't help. |
| `provider` | The app failed or refused the call | Read the message. It comes from the app. |
| `gateway` | Alpha is unavailable | Retry after a pause |

The agent uses the same connections inside the session. While you have at most 100 connected tools, they appear directly in its tool list. Above that, it searches for the one it needs instead, so a long list doesn't crowd its context. You don't need to do anything either way. The commands it uses are listed in [Inside a session's machine](https://docs.alpha.new/reference/machine-environment.md).

## What can the key reach?

The key speaks for you, for this one session, and for nothing else.

| The key | |
| - | - |
| Reaches | Every app and remote MCP server you've connected, from any of your sessions. A connection added later works with the existing key. |
| Doesn't reach | Local MCP servers, which run inside each session's machine, and your [secrets](https://docs.alpha.new/secrets.md), which the app reads from its environment instead. |
| Never contains | An app's password or token. Those stay with Alpha and the connector service. |
| Shows in the transcript as | `[redacted]`, so it never survives in the session's history. |
| Lasts | Until you rotate it or delete the session. It has no expiry date. |

Because the key reaches all your connections, treat it like a password for your whole set of integrations. Narrowing a key to some connections isn't possible.

## Next steps

> **[Connect an app](https://docs.alpha.new/integrations/connect-apps.md)**
>
> Sign in to Gmail, Slack or Notion once, and every session's key can use it.

> **[Republish after a rotate](https://docs.alpha.new/publish/manage.md#republish-your-changes)**
>
> A published app picks up the new key only on its next version.

> **[Build an AI agent](https://docs.alpha.new/agents/build-an-agent.md)**
>
> Agents you build call the same tools with the same two variables.

> **[Secrets](https://docs.alpha.new/secrets.md)**
>
> For a service with no connector, hand the app your own API key instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.