Appearance
Tool Permissions
Control which MCP tools agents can access.
Overview
Tool permissions follow a default-deny model—agents can only use tools explicitly granted to them.
Permission Format
Basic Tool Permissions
yaml
permissions:
tools:
- llm/chat # Specific tool
- retrieval/search # Another tool1
2
3
4
2
3
4
Wildcard Permissions
yaml
permissions:
tools:
- llm/* # All LLM tools
- retrieval/* # All retrieval tools
- voice/transcribe # Specific voice tool only1
2
3
4
5
2
3
4
5
Full Access (Not Recommended)
yaml
permissions:
tools:
- "*" # All tools - use with caution1
2
3
2
3
Tool Categories
| Category | Tools | Description |
|---|---|---|
llm/* | chat, embed, list_models | Language model access |
retrieval/* | search, rerank, search_and_rerank | Knowledge base |
voice/* | transcribe, synthesize, pipeline, voices | Audio processing |
document/* | ocr, process, status, list, delete | Document handling |
self_inspect/* | whoami, get_my_usage, list_my_tools | Agent introspection |
Granting Permissions
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": "Support Bot",
"permissions": {
"tools": [
"llm/chat",
"retrieval/search",
"retrieval/rerank"
]
}
}'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 Permissions
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": {
"tools": [
"llm/chat",
"retrieval/search",
"retrieval/rerank",
"voice/transcribe"
]
}
}'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
Permission Inheritance
Base Permissions
Define shared permissions:
bash
curl -X POST https://api.gateflow.ai/v1/mcp/permission-sets \
-H "Authorization: Bearer gw_prod_admin_key" \
-H "Content-Type: application/json" \
-d '{
"name": "basic-assistant",
"permissions": {
"tools": ["llm/chat", "retrieval/search"],
"models": ["gpt-5-mini"]
}
}'1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
Extend Base
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": "Advanced Bot",
"extends": "basic-assistant",
"permissions": {
"tools": ["voice/transcribe"]
}
}'1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
Result: Agent has llm/chat, retrieval/search, AND voice/transcribe.
Permission Errors
When an agent tries to use an unpermitted tool:
json
{
"error": {
"type": "permission_error",
"code": "tool_not_permitted",
"message": "Agent does not have permission to use tool: voice/synthesize",
"tool": "voice/synthesize",
"agent_id": "agent_abc123",
"permitted_tools": [
"llm/chat",
"retrieval/search"
]
}
}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
Conditional Permissions
Collection-Scoped Retrieval
yaml
permissions:
tools:
- retrieval/search
collections:
- support-docs # Can only search these collections
- product-docs1
2
3
4
5
6
2
3
4
5
6
Classification-Scoped Access
yaml
permissions:
tools:
- retrieval/search
- document/process
data_classification:
- public
- internal # Cannot access confidential or higher1
2
3
4
5
6
7
2
3
4
5
6
7
Checking Permissions
From Agent Code
python
from gateflow_mcp import MCPClient
client = MCPClient(agent_id="agent_abc123", api_key="gf-agent-...")
# Check permissions
whoami = client.call_tool("self_inspect/whoami", {})
print(f"Permitted tools: {whoami['permissions']['tools']}")
# Check specific tool
tools = client.call_tool("self_inspect/list_my_tools", {})
for tool in tools["tools"]:
status = "✓" if tool["allowed"] else "✗"
print(f"{status} {tool['name']}")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
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
Permission Templates
Support Bot
yaml
name: support-bot-permissions
permissions:
tools:
- llm/chat
- retrieval/search
models:
- gpt-5-mini
collections:
- support-docs
data_classification:
- public1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
Research Agent
yaml
name: research-agent-permissions
permissions:
tools:
- llm/chat
- llm/embed
- retrieval/search
- retrieval/rerank
- document/ocr
- document/process
models:
- gpt-5.2
- text-embedding-3-large
data_classification:
- public
- internal
- confidential1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Voice Agent
yaml
name: voice-agent-permissions
permissions:
tools:
- voice/*
- llm/chat
models:
- whisper-1
- gpt-5-mini
- eleven_turbo_v2_5
pipelines:
- voice-agent-fast1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
Best Practices
- Minimum necessary - Only grant required tools
- Use categories wisely -
llm/*is safer than* - Scope collections - Limit data access
- Review regularly - Audit permissions periodically
- Document purpose - Note why permissions are needed
Auditing Tool Usage
All tool calls are logged:
bash
curl "https://api.gateflow.ai/v1/mcp/agents/agent_abc123/audit-log?tool=retrieval/search" \
-H "Authorization: Bearer gw_prod_admin_key"1
2
2
json
{
"entries": [
{
"timestamp": "2026-02-16T10:30:00Z",
"tool": "retrieval/search",
"input": {"query": "password reset"},
"output_summary": "3 results",
"latency_ms": 120,
"cost": 0.001
}
]
}1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
Next Steps
- Model Allowlists - Restrict models
- Data Classification - Data access levels
- Default-Deny - Permission model