Tool Protection

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:

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

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).

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. 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. 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:

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 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.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

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