Skip to main content

​
Model Tools

These three tools manage model registrations on the gateway. Models represent specific AI models from a provider (e.g., deepgram/nova-3, openai/gpt-4o-mini) that the gateway can route requests to.

​
list_models

List every registered model on the gateway, including YAML-defined and GUI-managed models. Destructive: No

​
Input Schema

ParameterTypeRequiredDefaultDescription
modalitystring | nullNonullFilter by "stt", "llm", or "tts".
provider_idstring | nullNonullFilter by provider (e.g., "openai").
enabled_onlybooleanNotrueIf true, exclude disabled models.

​
Output

FieldTypeDescription
modelsarrayList of model objects.
countintegerTotal matching models.
Each model object:
FieldTypeDescription
model_idstringFull model identifier (e.g., "deepgram/nova-3").
modalitystring"stt", "llm", or "tts".
provider_idstringProvider this model belongs to.
model_namestringProvider-specific model name (e.g., "nova-3").
default_voicestring | nullDefault voice ID (TTS models only).
display_namestring | nullHuman-readable name (managed models only).
default_languagestring | nullDefault language code (managed models only).
sourcestring"yaml" or "db".
enabledbooleanWhether the model is active.

​
Example: All models

Invocation: 
{
  "name": "list_models",
  "arguments": {}
}
Response: 
{
  "models": [
    {
      "model_id": "deepgram/nova-3",
      "modality": "stt",
      "provider_id": "deepgram",
      "model_name": "nova-3",
      "default_voice": null,
      "source": "yaml",
      "enabled": true
    },
    {
      "model_id": "openai/gpt-4o-mini",
      "modality": "llm",
      "provider_id": "openai",
      "model_name": "gpt-4o-mini",
      "default_voice": null,
      "source": "yaml",
      "enabled": true
    },
    {
      "model_id": "cartesia/sonic-3",
      "modality": "tts",
      "provider_id": "cartesia",
      "model_name": "sonic-3",
      "default_voice": "sonic-english-female",
      "source": "yaml",
      "enabled": true
    }
  ],
  "count": 3
}

​
Example: Filter by modality and provider

Invocation: 
{
  "name": "list_models",
  "arguments": { "modality": "stt", "provider_id": "deepgram" }
}
Response: 
{
  "models": [
    {
      "model_id": "deepgram/nova-3",
      "modality": "stt",
      "provider_id": "deepgram",
      "model_name": "nova-3",
      "default_voice": null,
      "source": "yaml",
      "enabled": true
    }
  ],
  "count": 1
}

​
register_model

Register a new model from an existing provider. The provider must already be configured (either in YAML or added via add_provider). The generated model ID is {provider_id}/{model_name}. Destructive: No (creates a new resource)

​
Input Schema

ParameterTypeRequiredDefaultDescription
modalitystringYes"stt", "llm", or "tts".
provider_idstringYesMust match an existing provider.
model_namestringYesProvider-specific model name (e.g., "nova-3", "gpt-4o-mini").
display_namestring | nullNonullHuman-readable name for dashboards.
default_languagestring | nullNonullDefault language code (STT models).
default_voicestring | nullNonullDefault voice ID (TTS models).
configobject | nullNonullExtra provider-specific options.

​
Output

FieldTypeDescription
model_idstringThe generated model ID (e.g., "deepgram/nova-3").
modalitystringThe model’s modality.
provider_idstringThe provider.
model_namestringThe provider-specific name.
display_namestring | nullHuman-readable name.
default_voicestring | nullDefault voice.
default_languagestring | nullDefault language.
sourcestringAlways "db".
createdbooleanAlways true.

​
Errors

CodeWhen
PROVIDER_NOT_FOUNDThe specified provider_id is not configured.
MODEL_ALREADY_EXISTSA model with the same ID already exists (YAML or managed).
VALIDATION_ERRORStorage is not enabled.

​
Example

Invocation: 
{
  "name": "register_model",
  "arguments": {
    "modality": "stt",
    "provider_id": "deepgram",
    "model_name": "nova-3",
    "display_name": "Deepgram Nova 3",
    "default_language": "en"
  }
}
Response: 
{
  "model_id": "deepgram/nova-3",
  "modality": "stt",
  "provider_id": "deepgram",
  "model_name": "nova-3",
  "display_name": "Deepgram Nova 3",
  "default_voice": null,
  "default_language": "en",
  "source": "db",
  "created": true
}

​
delete_model

Delete a GUI-registered model. This is a destructive operation that uses the two-phase confirmation pattern. Only models added via register_model (source "db") can be deleted; YAML-defined models must be removed from the config file. Destructive: Yes

​
Input Schema

ParameterTypeRequiredDefaultDescription
model_idstringYesThe model ID to delete (e.g., "openai/gpt-4o-mini").
confirmbooleanNofalseMust be true to delete. Default returns a preview.

​
Output (preview, confirm=false)

The tool raises a CONFIRMATION_REQUIRED error containing:
FieldTypeDescription
model_idstringThe model to be deleted.
projects_affectedarrayProjects whose stacks reference this model.

​
Output (confirmed, confirm=true)

FieldTypeDescription
actionstring"deleted".
model_idstringThe deleted model ID.
projects_affectedarrayProjects that were affected.

​
Errors

CodeWhen
MODEL_NOT_FOUNDNo managed model with the given ID.
READ_ONLY_RESOURCEThe model is defined in YAML (cannot delete via MCP).
CONFIRMATION_REQUIREDCalled without confirm=true (returns preview).

​
Example: Preview

Invocation: 
{
  "name": "delete_model",
  "arguments": { "model_id": "deepgram/nova-3", "confirm": false }
}
Response (error envelope): 
{
  "error": {
    "code": "CONFIRMATION_REQUIRED",
    "message": "Deleting model 'deepgram/nova-3' will impact 1 project(s). Call again with confirm=True.",
    "details": {
      "model_id": "deepgram/nova-3",
      "projects_affected": ["tonys-pizza"]
    }
  }
}

​
Example: Confirm

Invocation: 
{
  "name": "delete_model",
  "arguments": { "model_id": "deepgram/nova-3", "confirm": true }
}
Response: 
{
  "action": "deleted",
  "model_id": "deepgram/nova-3",
  "projects_affected": ["tonys-pizza"]
}