Migrating MCP to KYA-OS

This guide is for adding KYA-OS to an existing MCP server. If you don't have one yet, deploy fresh instead:

• One-click deploy from the Checkpoint dashboard — creates a GitHub repo, Cloudflare Worker, and KYA-OS identity in minutes
• npx @kya-os/create-mcpi-app — scaffolds a ready-to-deploy KYA-OS server locally

Both give you a fully configured KYA-OS server with identity, consent, and proof verification out of the box.

Prerequisites

• An existing MCP server (Node/Express for Approach A, or any runtime you're willing to move to Cloudflare Workers for Approach B).
• A Checkpoint project and API key. See Credentials for how to find your Project ID and API key in Installations.

Why Add KYA-OS?

Standard MCP provides tool discovery and invocation — but it has no built-in concept of who is calling a tool, whether they're authorized, or what they did afterward.

KYA-OS adds an identity and authorization layer inside your MCP server runtime:

• Agent Identity — Every agent gets a persistent DID (Decentralized Identifier)
• Delegated Authorization — Users grant scoped permissions to agents via OAuth-style flows
• Cryptographic Proofs — Each request carries a signed proof of identity and authorization
• Audit Trail — Every tool invocation is logged with non-repudiable proof
• Constraint Enforcement — Time windows, allowed origins, and IP allowlists are enforced on every delegation. (A max_calls field exists on delegation constraints but is not currently enforced by @kya-os/bouncer-middleware; there are no delegation-level budget controls.)

Standard MCP:   Agent → Tool Request → MCP Server → Response

KYA-OS:          Agent → Tool Request → MCP Server (parse proof → verify via Checkpoint → execute) → Response
                                        ↑
                Middleware runs in-process; verification is a Checkpoint API call

What Changes

Your tools, prompts, and business logic stay the same. KYA-OS adds a verification step at the protocol layer before your tool code runs — agents are unaware of the cryptographic details.

Migration Approaches

There are two ways to add KYA-OS to your existing server:

Approach A: Bouncer Middleware (Recommended)

Add @kya-os/bouncer-middleware to your existing Express/Node.js server. This is the fastest path — you keep your existing MCP server and add proof verification as middleware.

Best for: Existing Node.js/Express MCP servers where you want to add authorization without rewriting.

Approach B: KYA-OS Cloudflare Adapter

Use @kya-os/mcp-i-cloudflare to build a new KYA-OS server on Cloudflare Workers with identity, proofs, and consent built in.

Best for: New servers, or when migrating to edge deployment on Cloudflare Workers.

Approach A: Add Bouncer Middleware

Step 1: Install the package

npm install @kya-os/bouncer-middleware

Step 2: Create a Checkpoint project

1. Go to the Checkpoint dashboard
2. Create a new project
3. Copy your Project ID and API Key

Step 3: Protect your tool endpoints

Add the middleware to routes that should require KYA-OS authorization. This shows the options relevant to migrating an existing endpoint — 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());

// Protected tool — requires KYA-OS proof 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'],
    reputationThreshold: 60,
  }),
  (req, res) => {
    const { agentDid, scopes, reputation } = req.bouncer;
    // Process checkout with verified agent identity
    res.json({ success: true, agent: agentDid });
  }
);

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

Step 4: Configure tools in the dashboard

Navigate to Policy → Auth and assign each tool an owning protection. The effective per-tool configuration your server reads back (at config.toolProtection.tools) looks like:

{
  "checkout": {
    "requiresDelegation": true,
    "requiredScopes": ["cart:write", "payment:process"]
  },
  "list-products": {
    "requiresDelegation": false,
    "requiredScopes": []
  }
}

Step 5: Set up a consent flow

Configure how users authorize agents under Policy → Auth. Choose an authentication method and customize the consent page branding.

Step 6: Test the flow

1. An agent initiates the OAuth flow to get a delegation
2. The user sees the consent page and approves
3. The agent receives a delegation reference
4. The agent creates a signed proof and includes it in the request body at _meta.proof.jws
5. Your middleware verifies the proof automatically

See Proof Verification for what the middleware checks on every request and the shape of req.bouncer after verification.

Approach B: KYA-OS Cloudflare Adapter

Step 1: Scaffold a new KYA-OS server

npx @kya-os/create-mcpi-app my-server

Or deploy via the Checkpoint dashboard — see Deploying a KYA-OS Server.

Step 2: Define your tools

import { MCPICloudflareServer } from '@kya-os/mcp-i-cloudflare';
import { defineConfig } from '@kya-os/mcp-i-cloudflare';

export function getRuntimeConfig(env: CloudflareEnv) {
  return defineConfig({
    vars: {
      ENVIRONMENT: env.ENVIRONMENT || 'production',
      AGENTSHIELD_API_KEY: env.AGENTSHIELD_API_KEY,
    },
  });
}

export default {
  async fetch(request: Request, env: CloudflareEnv, ctx: ExecutionContext) {
    const server = new MCPICloudflareServer({
      env,
      config: getRuntimeConfig(env),
    });
    return server.handleRequest(request, ctx);
  },
};

Step 3: Configure tool protection

Define which tools require authorization in the Checkpoint dashboard, or via the API. See Tool Protection for details.

Step 4: Deploy

Deploy to Cloudflare Workers using wrangler deploy or via GitHub Actions (auto-configured if you used the dashboard deployment flow).

Designing Your Scopes

When migrating, you need to define scopes for your tools. Follow the resource:action pattern:

files:read        — Read files
files:write       — Create and modify files
files:delete      — Delete files
cart:read         — View shopping cart
cart:write        — Modify cart contents
payment:process   — Execute payments
admin:manage      — Administrative operations

Scope Design Guidelines

Migration Checklist

Use this checklist to track your migration progress:

• Create a Checkpoint project and obtain API credentials
• Install @kya-os/bouncer-middleware or @kya-os/mcp-i-cloudflare
• Design scopes for your existing tools
• Add proof verification to sensitive tool endpoints
• Configure tool requirements in the Checkpoint dashboard
• Choose an authentication method (OAuth, Consent Only, Credentials)
• Customize the consent page branding
• Test the full flow: OAuth → consent → delegation → proof → tool call
• Monitor proof verification in the dashboard
• Review delegation activity and configure constraints

Error Handling

When proof verification fails, the middleware returns structured errors. See Proof Verification → Error Codes for the full table of codes, HTTP statuses, and meanings.

Next Steps

• Deploying a KYA-OS Server — One-click deployment from the dashboard
• Authentication Methods — Choose how users authorize agents
• Tool Protection — Configure per-tool scope requirements
• Proof Verification — How proofs work under the hood
• Consent Flows — Customize the user-facing consent experience