Appearance
Model Allowlists
Restrict which AI models agents can access.
Overview
Model allowlists ensure agents only use approved models, controlling costs and capabilities.
Configuring Allowlists
At Agent Creation
bash
curl -X POST https://api.gateflow.ai/v1/mcp/agents \
-H "Authorization: Bearer gw_prod_admin_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Cost-Efficient Bot",
"permissions": {
"tools": ["llm/chat", "retrieval/search"],
"models": [
"gpt-5-mini",
"text-embedding-3-small"
]
}
}'1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
Updating Allowlist
bash
curl -X PATCH https://api.gateflow.ai/v1/mcp/agents/agent_abc123 \
-H "Authorization: Bearer gw_prod_admin_key" \
-H "Content-Type: application/json" \
-d '{
"permissions": {
"models": [
"gpt-5-mini",
"gpt-5.2",
"text-embedding-3-large"
]
}
}'1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
Model Categories
Chat Models
yaml
permissions:
models:
# OpenAI
- gpt-5.2
- gpt-5
- gpt-5-mini
- gpt-5-nano
# Anthropic
- claude-opus-4-5-20251107
- claude-sonnet-4-5-20250929
- claude-haiku-4-5-20251015
# Google
- gemini-3-pro
- gemini-3-flash
- gemini-2.5-pro
# Mistral
- mistral-large-3
- mistral-small-31
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Embedding Models
yaml
permissions:
models:
- text-embedding-3-large
- text-embedding-3-small1
2
3
4
2
3
4
Audio Models
yaml
permissions:
models:
# STT
- whisper-1
- voxtral-mini-latest
# TTS
- eleven_multilingual_v2
- eleven_turbo_v2_5
- eleven_flash_v2_5
- tts-1
- tts-1-hd1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
Reranking Models
yaml
permissions:
models:
- rerank-english-v3.0
- rerank-multilingual-v3.01
2
3
4
2
3
4
Wildcard Patterns
Provider-Wide Access
yaml
permissions:
models:
- openai/* # All OpenAI models
- anthropic/* # All Anthropic models1
2
3
4
2
3
4
Model Family Access
yaml
permissions:
models:
- gpt-5* # All GPT-5 variants
- claude-sonnet* # All Claude Sonnet versions1
2
3
4
2
3
4
All Models (Not Recommended)
yaml
permissions:
models:
- "*" # All models - use with caution1
2
3
2
3
Cost Control
Tier-Based Restrictions
Free Tier:
yaml
permissions:
models:
- gpt-5-mini
- text-embedding-3-small1
2
3
4
2
3
4
Pro Tier:
yaml
permissions:
models:
- gpt-5-mini
- gpt-5.2
- claude-sonnet-4-5-20250929
- text-embedding-3-large1
2
3
4
5
6
2
3
4
5
6
Enterprise Tier:
yaml
permissions:
models:
- "*" # All models1
2
3
2
3
Cost Implications
| Model | Cost per 1M tokens | Typical Use |
|---|---|---|
| gpt-5-nano | $0.10 | Simple tasks |
| gpt-5-mini | $0.30 | Standard tasks |
| gpt-5 | $5.00 | Complex tasks |
| gpt-5.2 | $10.00 | Advanced reasoning |
| claude-opus-4-5 | $30.00 | Expert tasks |
Model Errors
When an agent requests a non-allowed model:
json
{
"error": {
"type": "permission_error",
"code": "model_not_allowed",
"message": "Model 'claude-opus-4-5-20251107' is not in the agent's model allowlist",
"requested_model": "claude-opus-4-5-20251107",
"allowed_models": [
"gpt-5-mini",
"gpt-5.2"
]
}
}1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
Automatic Fallbacks
Configure fallbacks when preferred model isn't allowed:
python
from gateflow_mcp import MCPClient
client = MCPClient(agent_id="agent_abc123", api_key="gf-agent-...")
# Agent tries to use gpt-5.2 but only has gpt-5-mini
result = client.call_tool(
name="llm/chat",
arguments={
"messages": [{"role": "user", "content": "Hello"}],
"model": "gpt-5.2",
"fallback_models": ["gpt-5", "gpt-5-mini"] # Will use gpt-5-mini
}
)
print(f"Model used: {result['model']}") # gpt-5-mini1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Checking Allowed Models
From Agent
python
# List allowed models
result = client.call_tool("llm/list_models", {})
for model in result["models"]:
if model["allowed"]:
print(f"✓ {model['id']}: {model['type']}")
else:
print(f"✗ {model['id']}: {model.get('reason', 'Not allowed')}")1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
From Admin API
bash
curl https://api.gateflow.ai/v1/mcp/agents/agent_abc123/permissions \
-H "Authorization: Bearer gw_prod_admin_key"1
2
2
Model Usage Tracking
Monitor which models agents use:
bash
curl "https://api.gateflow.ai/v1/mcp/agents/agent_abc123/usage?group_by=model" \
-H "Authorization: Bearer gw_prod_admin_key"1
2
2
json
{
"usage_by_model": {
"gpt-5-mini": {
"requests": 1500,
"tokens": 2500000,
"cost_usd": 0.75
},
"gpt-5.2": {
"requests": 200,
"tokens": 500000,
"cost_usd": 5.00
}
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
Best Practices
- Start restrictive - Begin with minimal models
- Consider costs - More expensive models = higher bills
- Match to task - Don't allow opus for simple chat
- Use fallbacks - Graceful degradation
- Monitor usage - Track model consumption
Common Patterns
Cost-Optimized
yaml
permissions:
models:
- gpt-5-mini
- gpt-5-nano
- text-embedding-3-small1
2
3
4
5
2
3
4
5
Quality-Focused
yaml
permissions:
models:
- gpt-5.2
- claude-sonnet-4-5-20250929
- text-embedding-3-large1
2
3
4
5
2
3
4
5
Voice-Enabled
yaml
permissions:
models:
- gpt-5-mini
- whisper-1
- eleven_turbo_v2_51
2
3
4
5
2
3
4
5
Next Steps
- Tool Permissions - Tool access control
- Data Classification - Data access levels
- Rate Limits - Usage limits