What is Tool Protection?

Tool protection lets you define per-tool access control for MCP-I (Model Context Protocol with Identity) 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.

How It Works

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

The agent includes an MCP-I 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

Navigate to Project → Control Access → Tools
Add a tool by name
Set whether it requires a delegation
Specify the required scopes
Save

Via the API

curl -X PUT https://kya.vouched.id/api/v1/bouncer/projects/{projectId}/config \
  -H "X-API-Key: $CHECKPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": {
      "checkout": {
        "requiresDelegation": true,
        "scopes": ["cart:write", "payment:process"]
      },
      "view-cart": {
        "requiresDelegation": false
      },
      "list-products": {
        "requiresDelegation": false
      },
      "update-profile": {
        "requiresDelegation": true,
        "scopes": ["profile:write"]
      }
    }
  }'

Configuration Options

Field	Type	Description
`requiresDelegation`	`boolean`	Whether the tool requires a valid MCP-I proof
`scopes`	`string[]`	Scopes the agent must have in its delegation

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 scopes array:

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

Server-Side Integration

Use the middleware configuration to enforce tool requirements:

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 includes all tool configurations, 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