What is Tool Protection?

Tool protection lets you define per-tool access control for KYA-OS servers. Each tool in your MCP server can require specific scopes and delegation verification, so AI agents can only call tools they've been explicitly authorized to use.

Prerequisites

A Checkpoint project and API key. See Credentials for how to find your Project ID and API key in Installations.
An MCP server with @kya-os/bouncer-middleware installed in front of the tool endpoints you want to protect — see Proof Verification if you haven't set that up yet.

How It Works

When an AI agent calls a tool on your MCP server:

The agent includes a KYA-OS proof with its request
Your server's middleware checks the proof against the tool's requirements
If the agent has a valid delegation with the required scopes, the call proceeds
If not, the request is rejected with an error

Agent calls tool "checkout" →
  Middleware checks: does agent have "cart:write" + "payment:process" scopes?
    Yes → Tool executes
    No  → 403 INSUFFICIENT_SCOPES

Configuring Tools

Via the Dashboard

Per-tool protection is managed at Policy → Auth (/dashboard/{orgId}/{projectId}/policy/auth):

Create a protection — an auth method (OAuth provider, credential provider, or consent-only) plus the scopes it grants
In the tool coverage table, assign that protection as the owner of each tool it should protect
Leave a tool unassigned to keep it open (no delegation required)
Save

Tool discovery and removal, and the per-tool scope display, have not moved yet — they remain on the legacy surface at /dashboard/{orgId}/{projectId}/control-access/tools (legacy surface, moving to Access).

Via the API

Your server reads its effective tool configuration from the config endpoint. Per-tool protection is embedded at config.toolProtection.tools, keyed by tool name:

curl -X GET https://kya.vouched.id/api/v1/bouncer/projects/{projectId}/config \
  -H "X-API-Key: $AGENTSHIELD_API_KEY"

{
  "success": true,
  "data": {
    "config": {
      "toolProtection": {
        "tools": {
          "checkout": {
            "requiresDelegation": true,
            "requiredScopes": ["cart:write", "payment:process"]
          },
          "list-products": {
            "requiresDelegation": false,
            "requiredScopes": []
          }
        }
      }
    }
  },
  "metadata": { "requestId": "...", "timestamp": "...", "cachedUntil": "..." }
}

The same endpoint accepts PUT with a {"config": {...}} body for server configuration updates. Assigning which protection owns which tool is a dashboard operation (Policy → Auth).

Configuration Options

Each entry in toolProtection.tools follows the canonical ToolProtection shape:

Field	Type	Description
`requiresDelegation`	`boolean`	Whether the tool requires a valid KYA-OS proof
`requiredScopes`	`string[]`	Scopes the agent must have in its delegation
`riskLevel`	`string` (optional)	Risk classification: `low`, `medium`, `high`, or `critical`
`authorization`	`object` (optional)	Auth requirement for the tool (OAuth provider, credentials, consent-only, …)

Tools That Don't Require Delegation

Some tools are safe to call without authorization — for example, read-only public data endpoints. Set requiresDelegation: false for these tools.

Tools That Require Delegation

Sensitive operations like creating orders, modifying data, or accessing user information should require delegations. The agent must have a delegation that includes all of the specified scopes.

Scope matching is exact. If a tool requires ["files:write"], the agent's delegation must include files:write specifically. A delegation with files:read alone will not suffice.

Scope Design

Design your scopes around resources and actions:

{resource}:{action}

Examples:
  files:read
  files:write
  files:delete
  cart:read
  cart:write
  payment:process
  profile:read
  profile:write
  admin:manage

Scope Hierarchy

Checkpoint does not enforce implicit scope hierarchies. files:write does not automatically include files:read. If a tool needs both, list both in the tool's requiredScopes array:

{
  "upload-file": {
    "requiresDelegation": true,
    "requiredScopes": ["files:read", "files:write"]
  }
}

Server-Side Integration

Use the middleware configuration to enforce tool requirements — this shows only the requiredScopes delta for a specific tool; see Proof Verification for the complete createBouncerMiddleware option reference:

import express from 'express';
import { createBouncerMiddleware } from '@kya-os/bouncer-middleware';

const app = express();
app.use(express.json());

// Protect checkout tool — requires delegation with specific scopes
app.post(
  '/tools/checkout',
  createBouncerMiddleware({
    apiKey: process.env.AGENTSHIELD_API_KEY!,
    projectId: process.env.AGENTSHIELD_PROJECT_ID!,
    requiredScopes: ['cart:write', 'payment:process'],
  }),
  (req, res) => {
    const { agentDid, scopes } = req.bouncer;
    // Process checkout...
    res.json({ success: true });
  }
);

// Public tool — no delegation required
app.get('/tools/list-products', (req, res) => {
  res.json({ products: [...] });
});

AGENTSHIELD_API_KEY is the KYA-OS/bouncer naming convention for the same dashboard API key the Checkpoint SDKs read as CHECKPOINT_API_KEY — two env names, one key. The middleware itself reads no environment variables; values are passed explicitly in its config.

Remote Configuration

Fetch tool configuration dynamically via the API:

curl -X GET https://kya.vouched.id/api/v1/bouncer/projects/{projectId}/config \
  -H "X-API-Key: $AGENTSHIELD_API_KEY"

The response embeds all tool configurations at config.toolProtection.tools, enabling dynamic enforcement without redeployment.

Next Steps

Proof Verification — How proofs carry scope information
Managing Delegations — Creating delegations with scopes
Consent Flows — Let users approve scope requests

Tool Protection

On this page