Tool Scoping

How It Works

Navil sits between your AI agent and the MCP server. When an agent calls tools/list, Navil intercepts the response and filters it based on the agent's configured scope. Tools outside the scope are invisible — the agent never knows they exist.

Configuration

Define scopes in your policy.yaml. Each scope declares a named list of tools that agents assigned to that scope can see:

scopes:
  read_only:
    description: "Read-only access to filesystem"
    tools:
      - read_file
      - list_directory
      - search_files

  data_analyst:
    description: "Database queries + file reading"
    tools:
      - database_query
      - read_file
      - list_directory

  ci_agent:
    description: "CI/CD pipeline tools"
    tools:
      - build
      - test
      - deploy

agents:
  - name: "research-agent"
    scope: read_only

  - name: "data-agent"
    scope: data_analyst

Wildcard and Default Scopes

Use the wildcard * to grant access to all tools. Define a default scope as the fallback for agents that don't match any named scope:

scopes:
  # Fallback for any agent without an explicit scope
  default:
    tools: "*"

  # Restricted scope — only these three tools are visible
  restricted:
    tools:
      - read_file
      - list_directory

  # Full access scope
  admin:
    tools: "*"

X-Navil-Scope Header

For HTTP/SSE transports, agents can declare their scope via the X-Navil-Scope header. The proxy reads the header and applies the matching scope from your policy file.

curl -H "X-Navil-Scope: read_only" \
     -H "Authorization: Bearer navil_cred_..." \
     http://localhost:9090/mcp/tools/list

For stdio-based agents (via the CLI shim), the scope is set using the --agent flag and resolved from the agent's entry in the policy file.

Redis Scope Sync

In production deployments, Navil syncs scope definitions to Redis so the Rust proxy can filter tools/list responses at wire speed without calling back to Python. Scopes are stored under the navil:scope:<name> key prefix as JSON arrays.

# Verify synced scopes in Redis
redis-cli GET navil:scope:read_only
# → ["read_file","list_directory","search_files"]

Scope Templates

Scope templates are pre-built configurations for common use cases. Use them as a starting point and customize for your environment:

Dashboard

The Scoping page in the local dashboard shows each agent's active scope, which tools are visible vs. hidden, and a live log of filtered tool calls. Access it at http://localhost:8484/scoping.