Govern: Self-Host (BYOK)

Goal

Deploy a KYA-OS server on your own infrastructure using the @kya-os/mcp-i packages. By the end of this cookbook, you'll have:

• A KYA-OS server running on Cloudflare Workers or Node.js
• Agent identity managed locally
• Full control over configuration and deployment
• Integration with Vouched KYA for delegation verification
• A working authorization flow: an agent that calls one of your tools is sent to a consent screen, the user approves the requested scopes (signing in with an identity provider first, if you configured OAuth or credentials), and the agent comes back holding a delegation your server verifies on every subsequent request

Best for: Teams who need full control over infrastructure, custom hosting requirements, or integration with existing deployments.

Prerequisites

• A Vouched KYA account with an API key
• Node.js 18+ (for local development); @kya-os/bouncer-middleware needs Node.js 20.19+ or 22.12+
• Either:
  • Cloudflare account (for Workers deployment)
  • Your own Node.js hosting (Express, Docker, etc.)

Time Estimate

30 minutes

Choose Your Deployment Target

Steps

npx @kya-os/create-mcpi-app my-mcp-server --platform cloudflare
cd my-mcp-server
npm install

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @kya-os/mcp-i-cloudflare wrangler

npx @kya-os/create-mcpi-app regenerate-identity

echo ".mcpi/" >> .gitignore

# .env
# Checkpoint API key (from dashboard: see /docs/credentials for where to find it)
CHECKPOINT_API_KEY=sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
CHECKPOINT_PROJECT_ID=proj_abc123def456

# Environment
ENVIRONMENT=production
NODE_ENV=production

# Server URL (where your server will be accessible)
BASE_URL=https://mcp.yourdomain.com

# Identity (for Cloudflare, set as KV or secrets)
MCP_IDENTITY_PRIVATE_KEY=base64-private-key-here

# Optional: Anthropic/OpenAI for LLM features
ANTHROPIC_API_KEY=sk-ant-xxxxx

wrangler secret put CHECKPOINT_API_KEY
wrangler secret put MCP_IDENTITY_PRIVATE_KEY
wrangler secret put ANTHROPIC_API_KEY  # Optional

name = "my-mcp-server"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[vars]
ENVIRONMENT = "production"

# Required: replay-attack prevention (the only mandatory KV binding)
[[kv_namespaces]]
binding = "NONCE_CACHE"
id = "your-kv-namespace-id"

# Optional: archives generated proofs for auditability
[[kv_namespaces]]
binding = "PROOF_ARCHIVE"
id = "your-kv-namespace-id"

# Optional: persistent agent identity storage
[[kv_namespaces]]
binding = "IDENTITY_STORAGE"
id = "your-kv-namespace-id"

# Required for OAuth/delegation flows: delegation storage
[[kv_namespaces]]
binding = "DELEGATION_STORAGE"
id = "your-kv-namespace-id"

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

export default createMCPIApp({
  AgentClass: MyMcpServerMCP,
  getRuntimeConfig,
  envPrefix: 'MY_MCP_SERVER', // Maps the prefixed KV binding (MY_MCP_SERVER_MCPI_KV) to standard names
});

// Export the Durable Object classes for Cloudflare Workers bindings
export { MyMcpServerMCP };
export { AuditProducer } from '@kya-os/mcp-i-cloudflare';

// 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';

  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];
}

# Development
wrangler dev

# Production
wrangler deploy

# Check DID document
curl https://your-server/.well-known/did.json

# Check agent metadata
curl https://your-server/.well-known/agent.json

# Health check (the Express example above serves /__health;
# scaffolded Cloudflare projects serve /health instead)
curl https://your-server/__health

# Test protected endpoint (should fail without delegation)
curl -X POST https://your-server/tools/read_file \
  -H "Content-Type: application/json" \
  -d '{"path": "/test"}'
# Expected: 401 Unauthorized

Adding Tools

Define tools as ToolDefinition objects: name, description, a JSON Schema inputSchema, and a handler. Which tools require a delegation (and with which scopes) is not declared in code: you configure it in the dashboard (next section). The Cloudflare runtime fetches that configuration and enforces it before the handler runs. The Node runtime does not read it yet, so on Node the scope check in your route (as in the Express example above) is what enforces.

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

export const tools: ToolDefinition[] = [
  {
    name: 'read_file',
    description: 'Reads content from a file',
    inputSchema: {
      type: 'object',
      properties: {
        path: { type: 'string', description: 'File path to read' },
      },
      required: ['path'],
    },
    handler: async (args: { path: string }) => {
      // Your implementation
      return { content: [{ type: 'text', text: 'file content' }] };
    },
  },
  {
    name: 'write_file',
    description: 'Writes content to a file',
    inputSchema: {
      type: 'object',
      properties: {
        path: { type: 'string' },
        content: { type: 'string' },
      },
      required: ['path', 'content'],
    },
    handler: async (args: { path: string; content: string }) => {
      // Your implementation
      return { content: [{ type: 'text', text: 'ok' }] };
    },
  },
];

Configure in Dashboard

Register your tools in the Vouched KYA dashboard:

1. Go to Policy → Auth
2. Create an auth method with the scopes it grants, and assign it as the owner of each tool in the coverage table. Pick OAuth or credentials if the user should sign in with an identity provider first; pick consent-only if approving the scopes is enough
3. Customize the consent screen text and branding on the same page

This enables the dashboard to show proper consent screens to users.

Prove Your Server's DID

A DID names one server across every org, so every POST /api/v1/kya-os/servers call proves the serverDid it names, including a re-registration of a DID your project already holds. A call with no proof answers 400 did_proof_required, naming the challenge endpoint.

A server that registers an OAuth resource proves its DID with resourceProof (next section). Any other server asks for a challenge with its DID alone and sends it back signed as didProof:

curl -X POST https://kya.vouched.id/api/v1/kya-os/servers/challenge \
  -H "X-API-Key: $CHECKPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serverDid":"did:key:z6Mk…"}'
# → { "challenge": "eyJ…", "expiresAt": "…" }   (valid 5 minutes, bound to this project and DID)

curl -X POST https://kya.vouched.id/api/v1/kya-os/servers \
  -H "X-API-Key: $CHECKPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "serverDid": "did:key:z6Mk…", "url": "https://mcp.example.com/mcp", "didProof": "<compact JWS>" }'

didProof is a compact JWS over {"challenge":"<challenge>"}, signed by a key the DID names. For a did:web, that is a key its DID document lists (alg EdDSA or ES256, kid a verification method under authentication or assertionMethod). For a did:key, it is the Ed25519 key the DID encodes (alg EdDSA), and nothing is fetched. A proof signed by any other key answers 403 invalid_did_proof. A DID method whose control cannot be proven answers 400 invalid_server_did.

registerServer in @kya-os/checkpoint-mcp 0.2.0 or later makes both calls on every registration, given the DID's key as signingKey: { privateKey, kid }. privateKey is a private JWK, a Node KeyObject or a WebCrypto CryptoKey. 0.1.0 sends no proof and gets 400 did_proof_required.

Register Your OAuth Resource

MCP clients that use OAuth (Claude, ChatGPT, Cursor) send the RFC 8707 resource parameter: your server's URL. Your org's authorization server issues a token only for a resource in its registry, and the token's aud is that resource's DID. A self-hosted server registers itself with the same POST /api/v1/kya-os/servers call, plus proof that it controls its did:web.

Two rules:

• serverDid must be a did:web on the resource URI's host, and a path DID's path must be a prefix of the URI's path: did:web:mcp.example.com or did:web:mcp.example.com:mcp for https://mcp.example.com/mcp, never did:web:mcp.example.com:other. Whoever serves the DID document at that place on the host can register the resource, and nobody else can.
• The resource URI is https, with no query, fragment or credentials. It is stored in canonical form: lowercase host, no default port, no trailing slash.

1. Ask for a challenge (project API key, write permission):

curl -X POST https://kya.vouched.id/api/v1/kya-os/servers/challenge \
  -H "X-API-Key: $CHECKPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serverDid":"did:web:mcp.example.com","resourceUri":"https://mcp.example.com/mcp"}'
# → { "challenge": "eyJ…", "expiresAt": "…" }   (valid 5 minutes, bound to this project, URI and DID)

2. Sign it and register. resourceProof is a compact JWS over {"challenge":"<challenge>"}, alg EdDSA or ES256, with kid set to a verification method your DID document lists under authentication or assertionMethod:

curl -X POST https://kya.vouched.id/api/v1/kya-os/servers \
  -H "X-API-Key: $CHECKPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serverDid": "did:web:mcp.example.com",
    "url": "https://mcp.example.com/mcp",
    "resourceUri": "https://mcp.example.com/mcp",
    "resourceProof": "<compact JWS>"
  }'
# → { …, "resource": { "uri": "https://mcp.example.com/mcp", "did": "did:web:mcp.example.com" } }

With @kya-os/checkpoint-mcp 0.2.0 or later, set resourceUri beside signingKey and registerServer sends both calls with resourceProof.

Vouched KYA fetches https://mcp.example.com/.well-known/did.json, verifies the signature against it, and only then writes anything. Re-registering the same resource is a no-op. A URI or DID another project holds answers 409 resource_conflict; a bad proof answers 403 invalid_resource_proof. Only 503 did_document_unavailable, sent with Retry-After, is worth retrying: Vouched KYA couldn't fetch the document this time (a timeout, a 5xx, or a 404 while a deploy switches over), and a server that registers as soon as it listens can ask before its host routes traffic to it. 403 did_document_invalid won't pass on retry: fix how the document is hosted. The host name must resolve in public DNS to a public address; serve the document directly (no redirects), under 64 KB, as valid JSON whose id is the DID.

Serve your own protected resource metadata at the RFC 9728 path-inserted URL (https://mcp.example.com/.well-known/oauth-protected-resource/mcp for the example), with resource set to the full resource URI and authorization_servers set to your org's issuer. Verify every token's aud against your serverDid.

Troubleshooting

Identity Not Loading

Delegation Verification Fails

• Check API key: Must be valid for your project
• Check project ID: The middleware authenticates with API key + project ID
• Check proof format: Proofs travel as a compact JWS at _meta.proof.jws in the request body

Cloudflare KV Issues

• KV not bound: Check wrangler.toml bindings
• KV namespace missing: Create with wrangler kv:namespace create

What You Learned

• How to scaffold a KYA-OS server project
• How to generate and manage agent identity
• How to deploy to Cloudflare Workers or Node.js
• How to add tools with scope requirements
• How to register with KnowThat.ai (optional)

Next Steps

Related Documentation

• Deployment Reference
• Proof Verification
• Tool Protection
• Package Hierarchy