Tool Protection

Configure KYA-OS tool-level access control and scope requirements

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 Vouched KYA 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:

  1. The agent includes a KYA-OS proof with its request
  2. Your server's middleware checks the proof against the tool's requirements
  3. If the agent has a valid delegation with the required scopes, the call proceeds
  4. 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):

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

The tool coverage table (the Tools table in card 02 Authentication methods) is the project's tool list. It fills itself from the sources below, and each row shows the scopes the tool declares under its name. Discover tools in its header runs discovery now; it appears once the project has an MCP server URL to discover from. Remove tool… in a tool's menu takes the tool out of the list and out of any sign-in method that protects it, after you confirm; it comes back when your server registers it again or an agent calls it. Both wait while the editor has unsaved changes.

The table lists the project's tools, from three sources. A server that registers with its tool list (registerServer in @kya-os/checkpoint-mcp, or POST /api/v1/kya-os/servers) adds them open, except a tool whose securitySchemes require an oauth2 token (no noauth scheme): it arrives protected by consent, with its oauth2 scopes as its scopes. When that server also registered its resource with a did:web proof, consent can grant the oauth2 scopes its protected tools declare; opening or removing such a tool withdraws them. A submitted proof adds the tool it was for. Discovery, which the Servers page runs for you when you deploy through it, adds whatever your server's tools/list returns: a new tool Vouched KYA rates risky arrives protected by consent, and the rest arrive open. The tool count on the Servers page is one server's own catalog, not this table, and nothing in it can be protected.

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: $CHECKPOINT_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).

Serving a protection is not enforcing it: the runtime has to fetch this config and refuse the call itself. @kya-os/mcp-i-cloudflare does. @kya-os/bouncer-middleware checks the requiredScopes you pass it and never reads this config, and @kya-os/checkpoint-mcp only registers and reports.

Configuration Options

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

FieldTypeDescription
requiresDelegationbooleanWhether the tool requires a valid KYA-OS proof
requiredScopesstring[]Scopes the agent must have in its delegation
riskLevelstring (optional)Risk classification: low, medium, high, or critical
authorizationobject (optional)Auth requirement for the tool (OAuth provider, credentials, consent-only, …)
amountobject (optional)Where the call's amount is: argument is a dot path into the tool arguments, and currency is an ISO 4217 code or { "argument": "<dot path>" }. When the agent's delegation carries a maxAmount on a scope the tool requires, the gateway refuses a call over that limit, in another currency, or without a readable amount. A tool with amount must require at least one scope, so setting amount on a tool that requires none is refused with a 422. Re-discovering the tool keeps its amount. A tool without amount is never checked.

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

Vouched KYA 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.CHECKPOINT_API_KEY!,
    projectId: process.env.CHECKPOINT_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: [...] });
});

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: $CHECKPOINT_API_KEY"

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

Next Steps