Skip to content

First Steps#

This guide walks you through the minimum setup to run your first AI request in OptScale AI: create an organization, connect a provider, assign allowed providers, add a guardrail, configure policies, connect MCP Servers, then use Chat or your application.

If you need background first, see Architecture Overview. For AIOps pages after LLM setup, see Model Training.

Create organization#

  1. Sign in to OptScale AI with an administrator account.
  2. Open the Organization selector in the header.
  3. Choose Create new organization, enter a display name.
  4. You are assigned the Organization manager role in the newly created organization and can invite other team members.

For the rest of the workflow, one active organization must be selected.

Add first provider#

Before you register your first provider, confirm that you have:

  • Permission to manage providers for the active organization.
  • Valid credentials for the vendor.

Steps:

  1. In the Admin UI, open Providers.
  2. Open the Providers tab—each row is one callable provider endpoint backed by a vendor configuration.

  3. Choose Add and fill in the provider form:

    • Name — A unique label for this configuration.
    • API type — Provider API format or integration type from the dropdown.
    • API key — Secret used to authenticate to the vendor.
    • Base URL — Provider endpoint URL for outbound calls.
    • Description — Optional notes for administrators; Markdown is supported.
    • Insecure — Optional toggle to disable SSL certificate verification for this provider. Use only for trusted internal or test endpoints.

  4. Save and wait until validation succeeds and the entry becomes available. If checks fail, verify key permissions, outbound network access to the vendor, the Base URL, proxy requirements, and clock skew.

  5. Add additional rows only if you need more providers exposed to Chat or to Routers.

You now have at least one healthy provider. Optional next step: add a routing rule for fallbacks and load balancing.

Add allowed providers#

After Add first provider, assign which Active providers your user may use. Follow Configure allowed providers in AI Access.

Add guardrail#

A guardrail is a reusable control you define once and link to policies. Use it for safety and compliance checks—such as detecting and handling personally identifiable information (PII)—before or after provider calls, depending on the Stage you choose.

  1. In the Admin UI, open Policies + Guardrails.
  2. Open the Guardrails tab and choose Add.

  3. Fill in the required fields (marked with * in the form):

    • Name — Unique label for this guardrail (for example pii-redact-input).
    • Description — Optional note for operators (what it protects and when to use it).
    • Stage — When evaluation runs in the request lifecycle (for example Input to inspect user prompts before the provider responds).
    • Type — The guardrail engine (for example PII detection and redaction). See Guardrail types for all available options.
    • Threshold — Confidence level for triggering the guardrail. See Guardrail thresholds for guidance on choosing values.
    • Policy — Action when the guardrail fires (for example Redact to mask detected entities instead of blocking the request).
    • PII fields — Which categories of PII to scan for when the type is PII-related.

  4. Optional: under Custom regexp patterns, choose + ADD PATTERN to match your own entity labels when built-in PII types are not enough. The panel shows No custom patterns until you add at least one rule.

  5. Click SAVE to create the guardrail, or CANCEL to discard changes.

Expected behavior after configuration

  • The guardrail appears on the Guardrails tab. Open it from the list to Edit the definition or review configuration on the detail page.
  • Policies using it shows 0 until you link the guardrail from a policy (Linked Guardrails on the Add Policy form or when editing an existing policy).
  • A guardrail does not enforce on traffic by itself. It runs only when linked to an Enabled policy and that policy's conditions match a request.
  • After matching traffic flows, evaluation runs at the guardrail's configured Stage; Total invocations and Violation rate on the guardrail detail page update once the guardrail executes.

Add policies#

Policies are evaluated against AI Gateway traffic. Each policy defines when it applies, how it is evaluated, and which guardrails run when it matches.

Warning

At least one linked guardrail is required before creating or configuring a policy. Create a guardrail first, then return to this step.

1. Open Policies + Guardrails in the Admin UI. 2. On the Policies tab, choose + ADD to open the Add Policy form.

3. Set Name and optional Description.

4. Use the Enabled toggle to turn enforcement on or off (disabled policies are kept but not applied).

Conditions

5. Under Conditions, define which requests this policy applies to. Conditions allow you to filter requests based on attributes such as request type, provider, model, team, and other supported fields. Policies support logical rule grouping:

  • AND — all rules in the group must match for the policy to apply.
  • OR — at least one rule in the group must match.
  • + Add rule — adds another condition to the current group.

  • + Add rule group — creates a nested group for building more advanced filtering logic.

    Nested groups can be combined to create complex policy scopes.

6. Review the CEL expression preview - verify the final condition logic.

Evaluation scope

7. Under Evaluation scope, configure:

  • Stage — Determines when the guardrail is executed during request processing (Input, Output, or Both).
  • Sampling rate — Defines what percentage of requests are evaluated by the guardrail. Reducing the sampling rate can help lower latency and reduce evaluation overhead.
  • Timeout — Specifies the maximum amount of time allowed for guardrail evaluation. If evaluation exceeds the configured timeout, the system follows the behavior defined by the Pass on timeout option.
  • Request type — Limits the guardrail to specific AI Gateway request types.

  • Pass on timeout — Defines what happens if evaluation does not complete within the configured timeout.

  • Enabled — the request proceeds even if evaluation times out.

  • Disabled — the request may be blocked or failed if evaluation does not complete in time.

Linked guardrails

8. Under Linked Guardrails, select which guardrails are associated with the policy.

A policy can include one or multiple guardrails. Only the selected guardrails are evaluated when the policy conditions match an AI Gateway request.

Each guardrail card displays:

  • Name or ID — identifier of the guardrail.
  • Type — the guardrail category or detection type.
  • Stage — when the guardrail is executed during request processing.
  • Description — additional information about the guardrail configuration.

Select Show configuration to expand and review the guardrail configuration details before linking it to the policy. This helps verify that the selected guardrail matches the intended policy behavior.

Use the checkbox next to each guardrail to include it in the policy. At least one linked guardrail is required before the policy can be created or saved.

9. Click SAVE to create the policy.

Expected behavior after configuration

  • The policy appears on the Policies tab. When Enabled, it is eligible to evaluate matching AI Gateway traffic; disabled policies are kept but not applied.
  • Requests that match Conditions and Request type enter evaluation at the configured Stage, subject to Sampling rate and Timeout settings.
  • When a request matches, linked guardrails run. Outcomes follow each guardrail's configured Policy action (for example Redact or block). If evaluation exceeds the timeout, Pass on timeout determines whether the request proceeds or fails.
  • Requests evaluated, Match rate, Violation rate, and Guardrail invocations on the policy detail Usage statistics tab populate after traffic. Use Traces to inspect individual outcomes—see Core Services — Traces.

Tighten conditions and guardrail selection after your first successful request; keep this pass minimal so you learn baseline behavior before layering stricter governance.

For common patterns, limitations, and a full walkthrough, see Architecture Overview — Policies and guardrails (use cases, limitations, end-to-end example).

Connect MCP Servers#

MCP servers expose tools and external context to AI assistants through the Model Context Protocol (MCP).

  1. In the Admin UI, open MCP Servers.

  2. Click + ADD to open the Add MCP Server page.

  3. Either complete the form manually or use Browse MCP presets to start from a curated configuration.

    • Presets

    At the top of the page, click Browse MCP presets to apply a predefined configuration for common MCP providers. Filter presets by category or search by server name to find the required preset. Each preset card displays an icon, title, and description of the integration capabilities to help with selection. Click a card and follow the instructions to automatically populate the configuration fields.

    Warning

    Preset configurations may require additional validation and customization. Review all pre-filled fields before saving, and provide any required sensitive information (for example, tokens, credentials, or API keys) manually.

    • Manual

      • Name — Unique MCP server identifier.

      • Connection settings

      Configure the following required fields:

      • Connection type — Communication method used by the server. By default, the page selects Streamable HTTP (HTTP).
      • MCP server URL — Server endpoint URL.
      • Authentication type — Authentication method used to connect to the MCP server. The default value is None.

    • Server options

      The Server options section contains operational settings and feature toggles:

      • Code mode client — Enables compatibility with code-oriented MCP workflows.
      • Ping available for health check — Allows the platform to use lightweight ping requests for server health checks. Disable this option if the MCP server does not support ping operations.
      • Allow on all virtual keys — Makes the MCP server available to all virtual keys within the organization.
      • Tool sync interval — Defines how often the platform synchronizes available tools from the MCP server.

  4. Click SAVE and wait for the server status to change to Connected. If needed, open the server details page and test tools on the TOOLS tab.

For information about list columns, the CONNECT integration tab, and the detail or edit pages, see Core Services — MCP Servers page.

After registration, verify that the server displays the Connected status on the MCP Servers page before using its tools in Chat.

Open Chat#

Chat is the interactive workspace for using providers after they have been configured.

  1. Open Chat — Click Go to Chat in the main navigation.

  2. Select an organization — Choose the organization where your work is scoped.

    • Use the Organization selector in the top-right corner.
    • Select the organization you configured earlier so the appropriate policies and provider catalog are available.
    • Providers, models, chat history, policies, and usage data are scoped to the selected organization.

  3. (Optional) Open the Admin Console — Return to organization settings without leaving Chat.

    • Click Go to Admin Console to configure providers, access controls, policies, and other settings. For more information, see Core Services.

  4. Select a provider — Use the Provider selector to choose the provider that processes your requests.

  5. Select a model — Use the Model selector to choose an available model from the selected provider.

  6. (Optional) Connect external tools — Retrieve connection values for OpenCode, Cursor, or other OpenAI-compatible clients.

    • Click Connect this model to external tools in the lower-left corner of the page.
    • Copy the Base URL, API Key, and Model Name displayed in the dialog.
    • Use these values to configure external tools. For more information, see Get connection values from Chat.

  7. Start chatting — Enter a prompt in the message composer and interact with the selected model.

    • Attach files or enable web search if allowed by your organization's policies.

  8. Manage your account — Open the Profile menu to access account settings or sign out.

For UI details, see Interface Overview.

To migrate an existing application from a direct vendor API to OptScale AI Gateway, see Switch to OptScale AI Gateway.

For AIOps setup (tasks, models, datasets, environments, and integrations), see Model Training, Experiment Tracking, and Environments & Operations.

Support email: [email protected] | Terms of use | © 2026 OptScale AI. All rights reserved | [email protected]