AI gateways - AIRCTRL

An gateway routes AI requests through provider credentials stored in . Applications use a gateway token instead of receiving the provider credential.

The complete flow

Choose an AI provider.
Add a provider credential.
Create a gateway in a project.
Attach the credential and choose routing defaults.
Create a gateway token.
Point your provider client at the returned data-plane URL.
Inspect logs, usage and key access.

List providers

const providers = await airctrl.listProviders()
const openai = providers.find((provider) => provider.slug === 'openai')
if (!openai) throw new Error('OpenAI is not enabled for this AIRCTRL deployment')

airctrl gateway providers

MCP request:

Show the AI providers currently enabled in AIRCTRL. Include each provider's
name and ID. Do not add a credential or change any gateway.

MCP tool used: list_providers

Add a provider credential

The credential value is accepted for validation and encrypted storage. It is never returned by list or read operations. SDK:

const credential = await airctrl.createProviderCredential({
  accountId: '00000000-0000-4000-8000-000000000001',
  providerId: openai.provider_id,
  label: 'Production OpenAI',
  apiKey: process.env.OPENAI_API_KEY!,
})

CLI reads the provider value from an environment variable named by the flag:

airctrl gateway provider-credential-create \
  --account 00000000-0000-4000-8000-000000000001 \
  --provider 00000000-0000-4000-8000-000000000070 \
  --label "Production OpenAI" \
  --api-key-env OPENAI_API_KEY

Put the value in an AIRCTRL_MCP_KEY_* environment variable and pass only that variable’s name.

Add an OpenAI provider credential named "Production OpenAI" to account
"00000000-0000-4000-8000-000000000001". Read the provider key from
"AIRCTRL_MCP_KEY_OPENAI_PRODUCTION". Show only the variable name and safe
credential details, then wait for my confirmation. Never print the key.

MCP tool used: add_provider_key

Create a gateway

const gateway = await airctrl.createGateway({
  accountId: '00000000-0000-4000-8000-000000000001',
  projectId: '00000000-0000-4000-8000-000000000010',
  name: 'Payments AI',
  slug: 'payments-ai',
  defaultProviderId: openai.provider_id,
  defaultModel: 'gpt-5',
  credentialBindings: [{
    credentialId: credential.credential_id,
    modelId: 'gpt-5',
  }],
})

airctrl gateway create \
  --account 00000000-0000-4000-8000-000000000001 \
  --project 00000000-0000-4000-8000-000000000010 \
  --name "Payments AI" \
  --slug payments-ai \
  --provider 00000000-0000-4000-8000-000000000070 \
  --model gpt-5 \
  --credential 00000000-0000-4000-8000-000000000200

MCP uses create_gateway for a bare gateway. Use setup_gateway when the same operation must validate a provider key, bind one live-catalog model, create the gateway, mint a token, and return connection information.

Create a bare AIRCTRL gateway named "Payments AI" in project
"00000000-0000-4000-8000-000000000010" under account
"00000000-0000-4000-8000-000000000001". Do not attach a provider key yet.
Show the proposed gateway details and wait for my confirmation before creating it.

MCP tool used: create_gateway

Create a gateway token

Gateway token plaintext is returned once.CLI command: gateway token-createStore the returned value before leaving the response. Listing tokens later returns metadata only.

const token = await airctrl.createGatewayToken(
  gateway.gateway_id,
  {
    name: 'Payments production',
    scopes: ['run'],
    allowedModels: ['gpt-5'],
    spendLimit: 100,
    spendWindow: 'monthly',
    rateLimitPerMin: 60,
  },
  { accountId: '00000000-0000-4000-8000-000000000001' },
)

MCP request:

Create a gateway token named "Payments production" for gateway
"00000000-0000-4000-8000-000000000030" in account
"00000000-0000-4000-8000-000000000001". Make it expire in 30 days. Show the
safe request details and wait for my confirmation. Return the token value only
once and only to the approved storage step.

MCP tool used: create_gateway_token

Connect an AI client

Use the gateway token with the URLs returned by get_connection_config or setup_gateway.

OpenAI-compatible SDKs use the /compat base URL.
OpenAI-native requests use the /openai/v1 path.
Anthropic clients use the /anthropic base URL.
Gemini-compatible clients use the returned Gemini endpoint.

The data plane speaks each provider’s normal protocol. It is not wrapped in separate SDK methods. MCP request:

Show the connection settings for gateway
"00000000-0000-4000-8000-000000000030". Include compatible base URLs and
required header names. Do not create or reveal a token.

MCP tool used: get_connection_config

Routing and settings

Use updateGateway, updateGatewaySettings, attachGatewayCredential, and detachGatewayCredential in the SDK. Gateway settings can control:

Spend limit and period.
Requests per minute.
Request logging and optional body logging.
Allowed models.
Guardrail mode.
Cache state and lifetime.

CLI commands: gateway update, settings, credential-attach, and credential-detach.

Review gateway "00000000-0000-4000-8000-000000000030". Propose a monthly
spend limit of 100 and a rate limit of 120 requests per minute. Show the exact
changes and wait for my confirmation. Do not change routing or credentials.

MCP tool used: set_gateway_settings

Logs and usage

Gateway logs show requests for one gateway.
Project usage combines gateways in one project.
Key access shows whether granted, denied, or failed to retrieve a provider credential.
Log-body reads require usage:read-bodies because prompts and responses can contain sensitive data.
Spend reads require usage:read-spend.

SDK methods include listGatewayLogs, getGatewayLogDetail, listGatewayKeyAccess, listUsageLogs, getUsageLogDetail, getUsageSpend, and getUsageMetrics.

OpenTelemetry

Use getGatewayOtelExport and updateGatewayOtelExport to configure metrics and traces. Stored header values are write-only and are never returned. CLI commands: gateway otel, gateway otel-update

Show the current OpenTelemetry export settings for gateway
"00000000-0000-4000-8000-000000000030" in account
"00000000-0000-4000-8000-000000000001". Return only safe settings and never
request stored header values. Do not change anything.

MCP tool used: get_otel_export

Common failures

403 plan_limit_reached: the account plan cannot create another gateway.
404 gateway_not_found: the gateway is unavailable in the active account.
400: a provider credential belongs to another account or a setting is invalid.
429: API rate limit, gateway rate limit, or spend limit. Read the error code before retrying.

​The complete flow

​List providers

​Add a provider credential

​Create a gateway

​Create a gateway token

​Connect an AI client

​Routing and settings

​Logs and usage

​OpenTelemetry

​Common failures