Goal

Deploy a fully configured KYA-OS server using Vouched KYA's managed deployment pipeline. By the end of this cookbook, you'll have:

A GitHub repository with production-ready KYA-OS server code
Automatic deployment to Cloudflare Workers
Agent identity (DID) registered with KnowThat.ai
Dashboard integration for monitoring delegations and proofs

Best for: Teams who want the fastest path to a running KYA-OS server without managing infrastructure setup.

Prerequisites

A Vouched KYA account
A GitHub account with the Vouched KYA GitHub App installed
A Cloudflare account (free tier works)

What Gets Created

When you complete this cookbook, Vouched KYA will create:

Component	Description
GitHub Repository	Private repo with KYA-OS server source code
Cloudflare Worker	Edge deployment of your KYA-OS server
Agent Identity	Ed25519 key pair with a DID (`did:key:z6Mk...`)
GitHub Secrets	Encrypted API keys and private keys
GitHub Actions	Auto-deploy workflow on push to main
Dashboard Project	Monitoring for delegations, proofs, sessions
KnowThat.ai Profile	Public agent profile (optional)

Steps

Connect GitHub

GitHub connects inline, the first time you need it. There's no separate integrations settings page:

Go to your Vouched KYA dashboard and open Servers
Start a new deployment (see the next steps). Once you choose Self-host, the Cloudflare Workers and Clone to repository providers show connect github until GitHub is connected: click it
Install the Vouched KYA GitHub App to your account or organization
Select which repositories to grant access (or all repositories)

Vouched KYA needs repository access to create the KYA-OS server repo and configure secrets.

Start the Deployment Wizard

In your dashboard, open Servers
Choose a template: Verifier (an authorization host), OpenAPI import, or Blank Canvas

Choosing a template opens the configuration form. OpenAPI import shows an import step for your OpenAPI spec first.

Configure Your Server

Fill in the configuration form. This cookbook deploys to your own GitHub and Cloudflare accounts, so it uses Self-host with the Cloudflare Workers provider:

Field	Required	Default	Description
Server name	Yes	None	What you call the server, for example `My AI Assistant`. Its slug (`my-ai-assistant`) becomes the GitHub repository name. A slug that matches a project in your organization shows name in use in this org, and the wizard won't create a new project with it
Project	Yes	New project · recommended	A new Vouched KYA project for the server, or an existing project in your organization to deploy into
Know That AI	No	On	Registers the server in the KnowThat.ai registry, where it earns a public trust score and other agents can discover it. Turned off, it gets no trust score and isn't discoverable; you can register later from the server page
Hosting	Yes	Managed	Choose Self-host. Managed runs the server on Vouched KYA's edge instead, with no repository of your own
Provider	With Self-host	None	Choose Cloudflare Workers: a GitHub repository, deployed as a Worker to the connected Cloudflare account. Clone to repository creates only the repository, and Download ZIP gives you the source as a file
Authoritative protocol audit	No	On, AAP-2 requested	Signed protocol events for the server. While it's on, you can change Assurance profile (AAP-1 or AAP-2), Retention (default 1 year), and Data residency (default Inherit project)

Cloudflare Workers needs both connections before Review deploy moves on:

Connection	How to connect
GitHub	Click connect github in the provider's row (see Connect GitHub)
Cloudflare	Click Connect with Cloudflare to connect your organization's Cloudflare account, or open or connect with an API token and paste a Cloudflare API token of your own, then click Connect Cloudflare. Members without owner or admin access see only the token field

If the Cloudflare account has no workers.dev subdomain yet, the wizard asks you to create one before you can deploy.

When your organization has a Cloudflare connection, the deploy uses it ahead of your own token, and it neither writes the token to the repository nor commits the auto-deploy workflow. A deploy with your own token saves it as the repository's CLOUDFLARE_API_TOKEN secret, so the workflow can redeploy on push.

Watch the Deployment Pipeline

Click Review deploy. The review screen lists everything the deploy will create; click Approve & deploy to start the pipeline. You'll see real-time progress through 10 steps:

Verify GitHub: Confirms the GitHub App installation
Check Repository Name: Confirms the repo name is available
Create Project: Creates the Vouched KYA project for monitoring
Generate API Key: Creates the encrypted API key for the worker
Register Identity: Generates the DID and registers it with KnowThat.ai (reports skipped only when reputation is opted out or no identity exists; a registration failure with reputation enabled reports an error)
Scaffold Files: Generates KYA-OS server source code
Create Repository: Creates the private GitHub repository
Commit Files: Pushes code to the repository
Add Secrets: Configures GitHub Secrets
Deploy to Cloudflare: Deploys the worker (skipped when Cloudflare credentials aren't connected yet)

Each step shows success/failure status. The entire process takes 1-2 minutes.

Review Your New Server

After successful deployment, you'll see:

Links:

GitHub Repository URL: Your new repo with full source code
Agent DID: Your agent's decentralized identifier
KTA Claim URL: Claim your agent profile on KnowThat.ai

Next Actions:

Deploy to Cloudflare: One-click deployment button
View Repository: Open GitHub to explore the code

Click Deploy to Cloudflare to deploy the worker, or push a commit to trigger the GitHub Actions workflow.

Add Cloudflare Credentials (if skipped)

If you chose Clone to repository instead, the repository has the auto-deploy workflow but no Cloudflare credentials:

Go to Cloudflare Dashboard
Navigate to Your Profile → API Tokens
Click Create Token
Use the Edit Cloudflare Workers template
Copy the token
In GitHub, go to your new repository
Navigate to Settings → Secrets and variables → Actions
Add two secrets:
- CLOUDFLARE_API_TOKEN: Your Cloudflare token
- CLOUDFLARE_ACCOUNT_ID: Your Cloudflare account ID (found in dashboard URL)
Push a commit or manually trigger the workflow to deploy

Configure Tool Protection

Define which tools require authorization and what scopes they need:

In your Vouched KYA dashboard, select your new project
Go to Policy → Auth
Create an auth method (OAuth, credentials, 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

Example assignments:

Tool	Owning protection grants	Requires delegation
`read_file`	`files:read`	Yes
`send_email`	`email:send`	Yes

Tools left unassigned stay open (no delegation required). This Tools table is the tool list, filled when your server registers and the first time an agent calls a tool. Discover tools in its header runs discovery on demand, and Remove tool… in a tool's menu removes one.

Test Your Server

Check the Well-Known Endpoints:

# Get agent DID document
curl https://your-worker.your-account.workers.dev/.well-known/did.json

# Get agent metadata
curl https://your-worker.your-account.workers.dev/.well-known/agent.json

Test Tool Execution (without delegation: should fail):

curl -X POST https://your-worker.your-account.workers.dev/tools/read_file \
  -H "Content-Type: application/json" \
  -d '{"path": "/etc/passwd"}'

# Expected: 401 Unauthorized - Delegation required

Understanding the Generated Code

Your repository contains:

my-ai-assistant/
├── src/
│   ├── index.ts               # Worker entry point (createMCPIApp)
│   ├── agent.ts               # Durable Object agent class (MCPIAgent)
│   ├── mcpi-runtime-config.ts # Runtime config + tool registry
│   └── tools/
│       └── greet.ts           # Example tool definition
├── wrangler.toml              # Cloudflare Workers config (DO + KV bindings)
├── package.json
├── tsconfig.json
├── .dev.vars.example          # Local secrets template
├── .gitignore
├── README.md
└── .github/
    └── workflows/
        └── deploy.yml         # Auto-deploy on push

Key file: src/index.ts

import { createMCPIApp } from '@kya-os/mcp-i-cloudflare';
import { MCPIAgent } from './agent';
import { getRuntimeConfig } from './mcpi-runtime-config';

export default createMCPIApp({
  AgentClass: MCPIAgent,
  getRuntimeConfig,
});

// Export Durable Object class for Cloudflare Workers binding
export { MCPIAgent };
// Separate SQLite audit producer; it does not share authorization/session state.
export { AuditProducer } from '@kya-os/mcp-i-cloudflare';

createMCPIApp builds the whole worker: MCP transport, well-known identity endpoints, consent pages, and delegation checks. src/agent.ts extends MCPICloudflareAgent and registers every tool from the config with automatic proof generation.

Key file: src/mcpi-runtime-config.ts

import { defineConfig, type CloudflareRuntimeConfig } from '@kya-os/mcp-i-cloudflare';
import type { CloudflareEnv } from '@kya-os/mcp-i-cloudflare';
import { greetTool } from './tools/greet';

export function getRuntimeConfig(env: CloudflareEnv): CloudflareRuntimeConfig {
  const environment = (env.MCPI_ENV || env.ENVIRONMENT || 'development') as
    | 'development'
    | 'production';

  // With CHECKPOINT_API_KEY set, proofs, tool protection and the admin
  // endpoints are configured from these vars.
  return defineConfig({
    environment,
    vars: {
      ENVIRONMENT: environment,
      CHECKPOINT_API_KEY: env.CHECKPOINT_API_KEY,
      CHECKPOINT_API_URL: env.CHECKPOINT_API_URL,
      CHECKPOINT_PROJECT_ID: env.CHECKPOINT_PROJECT_ID,
    },
  });
}

export function getTools() {
  return [greetTool];
}

GitHub repository secrets created (visible under Settings → Secrets in the generated repo):

Secret	Purpose
`MCP_IDENTITY_PRIVATE_KEY`	Agent's Ed25519 private key
`CHECKPOINT_API_KEY`	Worker → Vouched KYA API
`OAUTH_ENCRYPTION_SECRET`	Encrypts stored OAuth tokens
`CLOUDFLARE_API_TOKEN`	Deployment (only if you provided your own token)

Cloudflare worker secrets set during deploy (on the worker itself, not in GitHub):

Secret	Purpose
`CHECKPOINT_PROJECT_ID`	The worker's Vouched KYA project
`KTA_REGISTRATION`	Lets the proof service notify the reputation engine
`MCP_SERVER_URL`	Worker URL, used by consent/approval redirects

Adding Custom Tools

Extend your server with custom tools:

// src/tools/calendar.ts
import type { ToolDefinition } from '@kya-os/mcp-i-cloudflare';

export const getCalendarEventsTool: ToolDefinition = {
  name: 'get_calendar_events',
  description: 'Retrieves upcoming calendar events',
  inputSchema: {
    type: 'object',
    properties: {
      days: {
        type: 'number',
        description: 'Number of days to look ahead',
        default: 7,
      },
    },
  },
  handler: async (args: { days?: number }) => {
    const { days = 7 } = args;

    // Your calendar API integration
    const events = await fetchCalendarEvents(days);

    return {
      content: [{ type: 'text', text: JSON.stringify(events) }],
    };
  },
};

import { getCalendarEventsTool } from './tools/calendar';

export function getTools() {
  return [greetTool, getCalendarEventsTool];
}

Scope requirements (for example calendar:read) are not declared on the tool: assign them in the dashboard under Policy → Auth (see Configure Tool Protection above), and the runtime enforces the delegation before the handler runs.

Verify It's Working

Dashboard Verification

Go to Delegations: See active delegations
Go to Servers and open your server: its Activity tab lists the tool calls and detections attributed to it
Go to Analytics: View request patterns

API Health Check

curl https://your-worker.your-account.workers.dev/health
# Should return: OK

KnowThat.ai Profile

Visit your agent's public profile:

https://knowthat.ai/agents/your-agent-slug

Troubleshooting

Deployment Pipeline Fails

Step	Common Cause	Fix
Verify GitHub	App not installed	Reinstall GitHub App
Create Repository	Repo name exists	Choose a different name
Add Secrets	Insufficient permissions	Check GitHub App permissions

Cloudflare Deployment Fails

Invalid API token: Regenerate token with correct permissions
Invalid account ID: Check dashboard URL for correct ID
Worker name conflict: Edit wrangler.toml to change worker name

Identity Not Resolving

# Check DID document
curl https://your-worker.your-account.workers.dev/.well-known/did.json

If empty or error, check that MCP_IDENTITY_PRIVATE_KEY secret is set correctly.

What You Learned

How to deploy a KYA-OS server with managed infrastructure
What gets created (repo, worker, identity, secrets)
How to configure tool protection
How to extend with custom tools
How to verify the deployment

Next Steps

Goal	Next Cookbook
Full control over infrastructure	Self-Host (BYOK)
Add to existing MCP server	MCP to KYA-OS Migration
Configure auth methods	Auth Methods Reference
Understand delegations	Delegations

Govern: Dashboard Deploy (Managed)