Connect an agent

Connect an MCP client to Bex to inspect services, read logs, and perform operations permitted by your account. The remote server uses Streamable HTTP at https://api.bex.co/mcp; self-hosted installations use their own API origin.

MCP tools have real effects. Start by listing resources, confirm the intended workspace, and review a deployment plan before applying it.

Connect with browser authorization​

In Claude Code:

claude mcp add --transport http bex-api https://api.bex.co/mcp

Open /mcp in a Claude Code session, select the server, and complete browser sign-in and consent. See the Claude Code MCP reference for client-specific configuration.

Bex's OAuth discovery must be configured on the installation. For a client that lets you choose scopes, request bex.read for reads; add bex.write for mutations and bex.sensitive when the work requires secrets. Identity scopes such as openid and offline_access alone do not grant API access. Workspace roles still restrict every call.

Cursor also supports remote MCP authentication. Configure the Bex server URL and use the client's authentication action when offered. Follow the current Cursor MCP instructions for configuration and credential storage; do not assume every client needs a manually pasted token.

Headless clients​

For CI or a client using authorization headers, exchange a Bex API key using the API authentication recipe. Send the returned short-lived BEX_TOKEN as Authorization: Bearer … on MCP requests. The API reference is the graded REST endpoint catalogue. To build your own user-consented OAuth client (not an MCP-managed browser login), see User-authorized OAuth integrations.

For example, a Cursor configuration using an environment variable is:

{
  "mcpServers": {
    "bex-api": {
      "url": "https://api.bex.co/mcp",
      "headers": { "Authorization": "Bearer ${env:BEX_TOKEN}" }
    }
  }
}

The client process must receive the variable. Refreshing a token in another terminal does not update an already running client's environment. Renew the exchange and reload/restart the client as needed, or use browser OAuth with client-managed refresh. Never put an API-key secret directly in the bearer header.

Select a workspace and check access​

Ask the agent to call list_workspaces, identify the workspace you intend to operate in, and pass its returned ID as workspaceId to workspace-scoped tools. Use the server's advertised tool schemas for arguments; do not infer field names from REST or assume the workspace shown in a separate dashboard tab applies.

A useful first prompt is:

List my Bex workspaces. In the workspace I choose, list services and report their IDs and deployment state. Do not change any resources yet.

An empty service list can mean the workspace has no services. A permission or backend error is different; inspect the tool result before interpreting it.

Deploy a Blueprint​

Use render.yaml for the manifest. The MCP wire field retains the name bexYaml, and the validation tool is still called validate_bex_yml; these names do not imply the obsolete apps: manifest format is supported.

1. Read the manifest and call validate_bex_yml with its content in bexYaml.
2. Review validation errors, the resource plan, and estimated pricing. Fix errors and confirm the target workspace and intended changes.
3. Call deploy with workspaceId and bexYaml; optional repo and branch override those source settings in the manifest.
4. Inspect the returned services, databases, and other resources. Poll each resource with the appropriate tool and check deployment/build logs on failure.

Reapplying unchanged content is a no-op; changed services deploy. Validation before apply does not make a multi-resource deployment transactionally atomic. Protected-environment changes can require an explicit confirmation phrase.

A service reaching Running does not prove every workflow succeeded. Test the HTTP response for a web service, task progress for a worker, or execution result for a cron job. Public URLs and automatic deployments also depend on routing and Git integration.

Troubleshooting​

The Bex CLI's coding-agent launchers are a separate workflow: they choose a model provider for Claude Code. Their isolated configuration may require registering the MCP server in that configuration too. For the full command surface and grades, see the CLI reference. For the graded REST catalogue, see the API reference. See workspace roles for access rules and logs for deployment diagnosis.