# Connect services and secrets

Bindings supply what the recipe names but must not hard-code: URLs, tokens, and settings that differ by environment.

A **binding** is attached to a project, a runtime, or one environment, and applies to the next task that starts. Secrets stay outside the sandbox: the platform adds them to outgoing requests.

**You need:** `introspection login` and a deployed runtime ([Deploy your agent](/ship)).

## What to bind

| The recipe needs | Bind |
| --- | --- |
| An MCP server | An MCP endpoint, plus a credential for its token (`bindings mcp connect`) |
| An HTTP API called from agent code | An API endpoint, plus a credential for its header (`bindings endpoints create --kind api`) |
| A setting the code reads | A variable, read from `process.env` (`bindings variables create`) |
| A secret | A credential, used only as `${NAME}` in a header (`bindings credentials create`) |
| Your own model key (`byok` runtimes) | An LLM endpoint: see [Choose models](/patterns/models) |
| Slack or another OAuth app | A connector: see [Put your agent in Slack](/patterns/slack) |
| Each end user's own account | A user connection: see [Per-user tools](/patterns/per-user-tools) |

## 1. Store the secret

```bash
export SUPPORT_TOOLS_TOKEN='...'
introspection bindings credentials create --name SUPPORT_TOOLS_TOKEN --from-env SUPPORT_TOOLS_TOKEN
```

Values come from `--from-env`, `--from-file`, or `--from-stdin`, never a flag. Credentials are write-only.

## 2. Connect the MCP server

```bash
introspection bindings mcp connect --mcp-server-id support-tools \
  --endpoint-url https://mcp.example.com/mcp \
  --header 'Authorization=Bearer ${SUPPORT_TOOLS_TOKEN}' \
  --runtime support-agent --environment staging
```

`--mcp-server-id` must equal the server ID the recipe declares. For OAuth, pass `--connector <slug>` instead of a header ([Connect an MCP server](/build/mcp)).

## 3. Allow an API and set variables

```bash
introspection bindings endpoints create --name orders-api --kind api \
  --endpoint-url https://api.example.com --header 'Authorization=Bearer ${ORDERS_TOKEN}' \
  --runtime support-agent --environment staging
introspection bindings variables create --name SERVICE_REGION --from-env SERVICE_REGION
```

Agent code calls `https://api.example.com/...` with no secret; the header is added on the way out. An `api` endpoint with no header only allows the host ([Sandbox](/build/sandbox)).

## Scope a binding

Omit `--runtime` for the whole project. Omit `--environment` for every environment, **including `development`**. When several bindings apply, the most specific wins.

## Verify

```bash
introspection bindings mcp list --runtime support-agent -e staging
introspection bindings credentials list
```

`mcp list` shows every MCP server the recipe declares and the connection each one resolves to in that environment. Then run a staging task that uses the tool and read its conversation.

The dashboard's **Bindings** page shows the same.

A new value applies to tasks that start afterward; a running task may keep
the old one. For a leaked secret, also revoke it at the provider.

## Limits

| Not supported | Do this instead |
| --- | --- |
| Reading a credential in agent code | Use a variable for non-secret settings; put secrets in headers. |
| A different connector per task on one runtime | Use per-user connections, or a runtime per tenant ([Serve many customers](/patterns/multi-tenant)). |

Or ask your agent: "Connect our support-tools MCP server to support-agent in staging."

Connect services and secrets

Bindings supply what the recipe names but must not hard-code: URLs, tokens, and settings that differ by environment.

A binding is attached to a project, a runtime, or one environment, and applies to the next task that starts. Secrets stay outside the sandbox: the platform adds them to outgoing requests.

You need: introspection login and a deployed runtime (Deploy your agent).

What to bind

The recipe needs	Bind
An MCP server	An MCP endpoint, plus a credential for its token (`bindings mcp connect`)
An HTTP API called from agent code	An API endpoint, plus a credential for its header (`bindings endpoints create --kind api`)
A setting the code reads	A variable, read from `process.env` (`bindings variables create`)
A secret	A credential, used only as `${NAME}` in a header (`bindings credentials create`)
Your own model key (`byok` runtimes)	An LLM endpoint: see Choose models
Slack or another OAuth app	A connector: see Put your agent in Slack
Each end user’s own account	A user connection: see Per-user tools

1. Store the secret


export SUPPORT_TOOLS_TOKEN='...'
introspection bindings credentials create --name SUPPORT_TOOLS_TOKEN --from-env SUPPORT_TOOLS_TOKEN

Values come from --from-env, --from-file, or --from-stdin, never a flag. Credentials are write-only.

2. Connect the MCP server


introspection bindings mcp connect --mcp-server-id support-tools \
  --endpoint-url https://mcp.example.com/mcp \
  --header 'Authorization=Bearer ${SUPPORT_TOOLS_TOKEN}' \
  --runtime support-agent --environment staging

--mcp-server-id must equal the server ID the recipe declares. For OAuth, pass --connector <slug> instead of a header (Connect an MCP server).

3. Allow an API and set variables


introspection bindings endpoints create --name orders-api --kind api \
  --endpoint-url https://api.example.com --header 'Authorization=Bearer ${ORDERS_TOKEN}' \
  --runtime support-agent --environment staging
introspection bindings variables create --name SERVICE_REGION --from-env SERVICE_REGION

Agent code calls https://api.example.com/... with no secret; the header is added on the way out. An api endpoint with no header only allows the host (Sandbox).

Scope a binding

Omit --runtime for the whole project. Omit --environment for every environment, including development. When several bindings apply, the most specific wins.

Verify


introspection bindings mcp list --runtime support-agent -e staging
introspection bindings credentials list

mcp list shows every MCP server the recipe declares and the connection each one resolves to in that environment. Then run a staging task that uses the tool and read its conversation.

The dashboard’s Bindings page shows the same.

A new value applies to tasks that start afterward; a running task may keep the old one. For a leaked secret, also revoke it at the provider.

Limits

Not supported	Do this instead
Reading a credential in agent code	Use a variable for non-secret settings; put secrets in headers.
A different connector per task on one runtime	Use per-user connections, or a runtime per tenant (Serve many customers).

Or ask your agent: “Connect our support-tools MCP server to support-agent in staging.”