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-middlewareinstalled 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_SCOPESConfiguring 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
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:
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:manageScope 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
- Proof Verification: How proofs carry scope information
- Managing Delegations: Creating delegations with scopes
- Consent Flows: Let users approve scope requests