First Steps#

To get started with OptScale AI, complete the following steps:

1. Create or select an organization.
2. Add a provider.
3. Give your user access to the provider.
4. Open Chat.
5. Select a provider and model.
6. Send your first prompt.

After you complete the basic setup, you can add routing rules, policies and guardrails, MCP servers, and other governance or integration features.

For an overview of how these components work together, see Architecture Overview.

Create an organization#

1. Sign in to OptScale AI with an administrator account.

2. Open the Organization selector in the header.

3. Select Create new organization.

4. Enter an organization name and create the organization.

You are assigned the Organization manager role in the new organization and can invite other users.

Keep the organization selected while completing the remaining setup steps.

Add your first provider#

Add a provider so Chat and API clients have an AI endpoint they can use.

Follow Providers — Add provider, including the listed prerequisites.

At minimum, configure a provider connection and make sure it is active.

After the provider is available, continue with Configure provider access.

For routing configuration, see Routing Rules.

Configure provider access#

Users can only select providers they are allowed to access.

If you assigned Employees when adding the provider in the previous step, no additional configuration is required. Continue to Open Chat.

Otherwise:

1. Open Config → Credentials & Roles.
2. Find your user.
3. Add the required provider under Allowed providers.
4. Save the changes.

For more information, see Configure allowed providers.

Open Chat#

After the organization, provider, and provider access are configured, open Chat.

Open Chat in one of the following ways:

• Open Chat at https://<OptScale AI host>/chat.
• From the Admin Console, open How to Use → Chat and use the button or link on that page.

Then:

1. Select the Organization you configured.
2. Select an available Provider.
3. Select a Model from that provider.
4. Click NEW CHAT if needed.
5. Enter a prompt in the message composer and send it.

If the provider or model you expect does not appear, verify the provider configuration and your Allowed providers settings.

For Chat layout and controls, see Interface Overview.

Verify your first request#

After sending a prompt:

• Confirm that Chat returns a response.
• Verify that the expected provider and model were used.
• If needed, open Analytics → Traces in the Admin Console to inspect the request lifecycle.

If the request fails, check:

• Provider status and credentials.
• Allowed provider configuration.
• Model availability.
• Organization selection.
• Relevant trace details in Analytics → Traces.

For provider troubleshooting, see Providers.

Add policies and guardrails#

This step is optional after the basic request flow is working. Add policies and guardrails when your organization needs to control how AI requests are evaluated and handled.

Use governance controls to:

• Apply safety or compliance checks to prompts and responses.
• Restrict evaluation to specific users, teams, providers, models, or request types.
• Redact, block, or otherwise handle content that matches configured guardrail conditions.
• Apply different controls at different stages of the request lifecycle.

A guardrail is a reusable control that evaluates request or response content. A policy defines when one or more guardrails should run.

The general workflow is:

1. Create a guardrail.
2. Create a policy.
3. Define the policy conditions and evaluation scope.
4. Link the required guardrails.
5. Enable the policy.
6. Send matching traffic and verify the result.

A guardrail does not enforce anything by itself. It runs only when it is linked to an enabled policy and that policy matches a request. For how these controls work together, see Policies & Guardrails and Architecture Overview.

Add an MCP server#

This step is optional. Add an MCP server when Chat or API workflows need access to external tools or data sources under organization-controlled access.

Administrators configure MCP servers in the Admin Console, including connection settings, authentication, tool availability, and access controls.

For setup instructions, see Add an MCP server.

Connect external tools#

This step is optional. Connect compatible external tools such as OpenCode or Cursor when you want to use an OptScale AI model outside Chat.

In Chat, select the required Organization, Provider, and Model, then open Connect this model to external tools to retrieve:

• Base URL
• API key
• Model name

Use these values in the external tool configuration.

For details, see External Tools.

Next steps#

After your first request succeeds, continue with the areas relevant to your deployment:

• Manage Chats and Projects — Organize Chat work.
• Providers — Add or manage provider connections.
• Routing Rules — Configure fallback and traffic routing.
• Policies & Guardrails — Add governance controls.
• MCP Servers — Connect external tools and data sources.
• External Tools — Connect compatible AI clients.
• Analytics → Traces — Inspect request behavior.
• Switch to OptScale AI Gateway — Point existing SDK or HTTP clients at the gateway.