Add and configure connectors in Frontier Tuning

Configure a catalog connector in an existing Frontier Tuning environment, check its saved settings, and inspect evidence from an authorized tool call before larger runs. This guide is for agent creators who already have the CLI, environment access, and a matching skill and test query.

The primary path uses a visible, non-instance, service-owned catalog mock in an approved test environment. A real, non-instance catalog connector is an alternate that can require service sign-in. Direct custom MCP sources outside the catalog aren't part of this procedure. For tool types and stage behavior, see Tools and connectors in Frontier Tuning.

Prerequisites

  • A Frontier Tuning CLI installation supported for your environment. Use the Install and Authentication guidance in the official CLI reference for setup.
  • An approved existing test environment, its exact ID, and permission to configure its connectors with your intended account. For real connectors, also confirm permission to access the service data and perform the intended action.
  • A visible, non-instance catalog connector and an existing skill, harmless query, and data that match its tools. For the primary path, confirm that the service-owned mock supports that scenario.
  • Authorization to use the selected data and tools, and a decision about service-run costs before verification.

Select and check the tuning environment

The source connector examples below don't include an environment flag. Select the intended environment in the same terminal session before using them. Don't create or import an environment just to select one.

  1. Set the documented session default in PowerShell. Replace <environment-id> with the approved existing environment's exact ID. This supporting setup uses the CLI reference's FRONTIER_TUNING_ENV_ID default and doesn't change a saved profile.

    $env:FRONTIER_TUNING_ENV_ID = "<environment-id>"
    

    An explicit -e option overrides this default. Check the assignment whenever you open another terminal or change environments. A configuration profile selects settings, not an identity; don't silently change a shared profile to switch accounts.

  2. Check the signed-in account and access to the selected environment with these supporting commands from the CLI reference.

    frontier-tuning auth whoami
    frontier-tuning auth check
    frontier-tuning auth probe
    

    auth probe verifies sign-in and selected-environment access. If the account is wrong, use the reference's interactive account-selection guidance in a terminal, then repeat the checks. Stop on an access or authentication failure; ask the resource owner or administrator to resolve it. Don't copy or share tokens or credential caches.

  3. Review the environment's existing reachable tools and the proposed query with its owner before enabling a connector. A mock selection or catalog label isn't a mock-only isolation boundary. If you can't establish a safe matching skill, query, and data context, stop before runtime testing.

Add a catalog connector

Use the mock primary path unless a real connector and its test actions have separate authorization. Replace <connector-id> in each example with the exact identifier returned by discovery, not a tool name, source prefix, or package-derived value.

  1. Find the connector. List the catalog connectors visible to the selected environment.

    frontier-tuning tools discover
    

    Visibility depends on tenant, environment, and shared access. Available doesn't mean enabled, even if the reported sign-in state is connected.

  2. Inspect it. Check its category, required instance parameter, member tools, enabled settings, and reported sign-in state.

    frontier-tuning tools get <connector-id>
    

    If an instance parameter is advertised, stop this generic enable flow and use Account for connector category differences. When tools report optional Mock or Live kind metadata, inspect each tool: a connector can contain mixed kinds, and an omitted kind means unknown.

    A mock's tool details can be empty before you first enable it. Inspecting a previously saved mock can prepare its tools for use.

  3. Enable it. Enable the selected non-instance connector only after confirming the approved scenario.

    frontier-tuning tools enable <connector-id>
    

    Both the connector and the individual tool must be enabled for the agent to use the tool. For a service-owned mock, first enable saves a package copy for the environment; later enables reuse it when it matches the catalog version. Recheck details after enabling if they were previously empty.

  4. Sign in, if required. Skip this step for the service-owned mock. For the real-connector alternate, run the command only if the enabled connector reports a sign-in requirement, then complete the displayed flow in your browser.

    frontier-tuning tools connect <connector-id>
    

    Signing in to the service's website alone doesn't connect the connector. This command uses table output, doesn't enable the connector, and can report a request failure or timeout. Inspect its state before retrying an uncertain connection outcome.

  5. Check it. Review the saved connector state.

    frontier-tuning tools status <connector-id>
    

    Use tools get again to inspect member settings. Neither command tests whether tools can run: status JSON reports observedCallableCount as null and discoveryStatus as unverified. A saved setting or connected sign-in state isn't proof of a successful tool call.

Choose connector stages

Choose the connector's stages according to your authorized scenario. The following two source commands are alternatives, not a batch: use the first to select inference and evaluation, or the second to select all three stages. Replace <connector-id> in the chosen command.

# Use a connector only for inference and evaluation
frontier-tuning tools update <connector-id> --label Inference --label Evaluation

# Restore all three stages
frontier-tuning tools update <connector-id> --label Inference --label Evaluation --label Finetuning
  1. Run only the alternative that matches your intended selection. Each update replaces, rather than appends to, the previous selection. Use Finetuning in command inputs and JSON, even when human-readable output displays Tuning.

    To exclude the catalog connector from all three stages instead, use tools update <connector-id> --clear-labels by itself. This saves an explicit empty selection; it doesn't remove registration or restore defaults. No stored selection defaults to all three stages. An empty array or none means no labels are selected; an absent field doesn't mean empty.

  2. Read back the connector with tools get or tools status. Labels apply to the whole connector, including tools and instances, subject to catalog policy and enablement. An update doesn't change connector or member-tool enablement.

    Label support depends on the selected environment. If the service rejects or doesn't confirm the selection, inspect the saved settings before retrying. Configuring a previously unregistered connector can register it as enabled under normal environment behavior.

  3. Allow for saved-versus-effective settings. Wait five minutes after changing labels before starting a new training job in a separately approved workflow. Running jobs keep the connector settings they started with.

Connector labels don't restrict hosted mock bindings or built-in tools. They don't establish a mock-only environment or guarantee real/mock pairing.

Change an individual tool setting

This optional action is for supported Environment Connectors, not individual actions within built-in sources. Use the connector ID and the exact member ID from tools[].id in tools get JSON. Don't substitute a member name, source prefix, or direct custom MCP source ID.

The source commands below are alternatives: disable the selected tool or enable it. Don't run both as a sequence.

frontier-tuning tools disable <connector-id> --tool-id <tool-id>
frontier-tuning tools enable <connector-id> --tool-id <tool-id>
  1. Replace both placeholders and run only the intended action. Avoid concurrent edits to the same connector, which can overwrite another editor's changes.
  2. Read back the connector with tools get and confirm the selected tool's enabled setting. Other tools retain their settings. If the outcome is uncertain, inspect before retrying.

Enabling a member tool doesn't enable a disabled connector. Don't use whole-connector enable/disable commands for instance-managed connectors.

Verify tool behavior before larger runs

Separate an authored-asset quality report from evidence of a successful tool call. Before either service-run step, confirm authorization, data handling, and the cost decision with the environment owner. The quality check isn't a free local validator, and the CLI doesn't estimate its cost.

  1. With approval, run the authored-asset check using this supporting command from the CLI reference.

    frontier-tuning health quality check
    

    It starts or joins a service run, waits, and reports scores, check judgments, and recommendations. Keep the accepted evaluation ID. Retrieve that same run with health quality status <evaluation-id> or health quality result <evaluation-id> if needed; don't repeatedly start checks.

    Pending, unavailable, partial, or degraded results aren't success evidence. A quality score doesn't establish whether tools can run or validate real-to-mock behavior.

  2. Reconfirm the reachable tools and approve one harmless query that fits the existing skill and selected tool's data. Use this supporting execution syntax from the CLI reference, replacing the query placeholder with your approved input. No particular sample or template is guaranteed to support it.

    Run this command in an interactive terminal. It can pause for approval before returning. Inspect every pending tool name and argument; reject with n or Enter if uncertain. Don't use conversation grants (t or a) or pipe approval.

    frontier-tuning executions run -q "<approved-harmless-query>" --wait
    

    The environment selects the skill; this command doesn't select one by ID. Retain the execution and conversation IDs. If submission is ambiguous, inspect execution history before starting another run. If a local wait times out, inspect the same execution; a timeout doesn't cancel the server run.

  3. If permission is requested, inspect every pending tool name and argument before deciding. Reject with n or Enter if uncertain. y approves only the pending tools for this execution. Conversation grants (t or a) can suppress later prompts; don't use them for this bounded test or pipe approval into the command.

    Prompts are conditional, not guaranteed for every action. JSON or redirected input can leave approval pending without a decision. For complete pending details, use the supporting read command below before making an interactive decision.

    frontier-tuning executions get <execution-id> -o json
    
  4. Inspect the actual execution trace and result for the intended tool call. Compare the complete tool name, including any returned source prefix, its arguments, and its result with the approved test. A completed chat reply alone doesn't prove that the target skill or tool ran.

    Retrieve status and results with executions get <execution-id>. If the execution failed, use the CLI reference's separate executions diagnostics <execution-id> guidance. A missing diagnostic document isn't proof of success. If evidence of the selected tool call is missing, stop rather than certify readiness.

  5. Record unresolved failures before considering larger runs. For access errors, check account and resource access. For throttling or service failures, retain the service guidance and transaction ID; don't repeatedly retry writes. Redact sensitive arguments, prompts, account details, and responses from support reports, and never include tokens or caches.

A small evaluation is a separately authorized next workflow. Use the tuning process to plan it, rather than appending an evaluation or training run to connector setup.

Account for connector category differences

These boundaries explain when to leave the generic procedure; they aren't executable instance-provisioning or custom-registration alternatives.

Category Configuration boundary
Instance-managed connector. Inspect the advertised parameter name and description with tools get. For Dataverse, orgName is the organization subdomain, not a URL; don't assume other connectors use that parameter. The first instance enables the connector, and removing the last disables it. Whole-connector enable/disable toggles aren't supported. Use the CLI reference's tools instances guidance for a separately approved procedure.
Direct custom MCP source outside the catalog. It doesn't appear in tools discover or tools get. For an already configured source, inspect execution traces and host logs, not a guessed connector ID.
Already configured custom host. Confirm service-side reachability, configured authentication audience and tenant authorization, and expected behavior after restarts and under planned user/session load. Don't disable authentication to work around a failure. Confirm a harmless request reaches a host you control and returns the expected result.

Disable or remove a connector

Cleanup is optional. Before removal, confirm the selected environment, exact connector ID, and any dependent instances with the owner. Deletion removes the environment's connector registration, settings, and all its instances. If you want to keep registration, use tools disable <connector-id> where whole-connector toggles are supported.

For a mock, disabling keeps the saved package and settings. Deletion doesn't erase the saved package or confirm test-data erasure or reset. Environment export/import isn't a complete connector backup: connector definitions, credentials, tool settings, and instances aren't copied.

Use this source command only after confirming the environment and connector ID:

frontier-tuning tools delete <connector-id>
  1. If removal is authorized, recheck the session environment and connector details. Run frontier-tuning tools delete <connector-id> in an interactive terminal and review the confirmation. Don't bypass confirmation or use unattended deletion.

  2. Inspect the catalog and, if applicable, remaining instance records in the same environment. Removal can take several minutes. If the result is ambiguous, inspect before retrying; don't assume the write failed or delete again to clear a lifecycle conflict.