Govern: Self-Host (BYOK)

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

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @kya-os/bouncer-middleware @kya-os/mcp-i express
npm install -D typescript @types/express @types/node

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @kya-os/mcp-i express
npm install -D typescript @types/express @types/node

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./dist
EXPOSE 3000
CMD ["node", "dist/index.js"]

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

npm install -D @kya-os/create-mcpi-app

// scripts/generate-identity.mjs
import { generateIdentity } from '@kya-os/create-mcpi-app/helpers';
import fs from 'node:fs';

const identity = await generateIdentity();
fs.mkdirSync('.mcpi', { recursive: true });
fs.writeFileSync('.mcpi/identity.json', JSON.stringify(identity, null, 2));
console.log(`Generated DID: ${identity.did}`);

node scripts/generate-identity.mjs

{
  "did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
  "kid": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#key-1",
  "privateKey": "base64-encoded-private-key",
  "publicKey": "base64-encoded-public-key",
  "createdAt": "2024-01-15T10:00:00.000Z",
  "type": "development"
}

wrangler secret put AGENTSHIELD_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"

npm install dotenv

import 'dotenv/config';

// 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,
      AGENTSHIELD_API_KEY: env.AGENTSHIELD_API_KEY,
      AGENTSHIELD_API_URL: env.AGENTSHIELD_API_URL,
      AGENTSHIELD_PROJECT_ID: env.AGENTSHIELD_PROJECT_ID,
    },
  });
}

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

// src/index.ts
import express from 'express';
import { createBouncerMiddleware } from '@kya-os/bouncer-middleware';
import { createMCPIRuntime } from '@kya-os/mcp-i';

const app = express();
app.use(express.json());

// Initialize the KYA-OS runtime. It loads its own identity:
// MCP_IDENTITY_PRIVATE_KEY / MCP_IDENTITY_PUBLIC_KEY / MCP_IDENTITY_AGENT_DID
// env vars when set, otherwise .mcpi/identity.json.
const runtime = createMCPIRuntime({
  identity: {
    environment: process.env.ENVIRONMENT === 'production' ? 'production' : 'development',
    devIdentityPath: '.mcpi', // directory containing identity.json
  },
});
await runtime.initialize();
const identity = await runtime.getIdentity();

// Well-known endpoints
const wellKnown = runtime.createWellKnownHandler({
  serviceName: 'My MCP Server',
  serviceEndpoint: process.env.BASE_URL,
});

app.get('/.well-known/did.json', async (req, res) => {
  const response = await wellKnown('/.well-known/did.json');
  if (response && 'status' in response) {
    res.status(response.status).set(response.headers).send(response.body);
  } else {
    res.status(404).end();
  }
});

app.get('/.well-known/agent.json', async (req, res) => {
  const response = await wellKnown('/.well-known/agent.json');
  if (response && 'status' in response) {
    res.status(response.status).set(response.headers).send(response.body);
  } else {
    res.status(404).end();
  }
});

// Protected tool endpoints
app.post(
  '/tools/:toolName',
  createBouncerMiddleware({
    apiKey: process.env.AGENTSHIELD_API_KEY!,
    projectId: process.env.AGENTSHIELD_PROJECT_ID!,
  }),
  async (req, res) => {
    const { toolName } = req.params;
    const { scopes } = req.bouncer;

    // Verify scope for this tool
    const requiredScope = `${toolName}:execute`;
    if (!scopes.includes(requiredScope)) {
      return res.status(403).json({
        error: 'Insufficient scope',
        required: requiredScope,
        granted: scopes,
      });
    }

    // Execute the tool through the runtime — it runs your handler and
    // generates a signed proof automatically. Proofs stay out-of-band
    // (runtime.getLastProof()), never in the response body.
    const result = await runtime.processToolCall(toolName, req.body, async (args) =>
      executeToolInternal(toolName, args)
    );

    res.json(result);
  }
);

// Health check
app.get('/__health', (req, res) => {
  res.json({ status: 'ok', did: identity.did });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`KYA-OS server running on port ${PORT}`);
  console.log(`Agent DID: ${identity.did}`);
});

# Development
wrangler dev

# Production
wrangler deploy

npm run build
node dist/index.js

npm install -g pm2
pm2 start dist/index.js --name mcp-server

# Build
npm run build
docker build -t my-mcp-server .

# Run
docker run -p 3000:3000 \
  -e AGENTSHIELD_API_KEY=sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -e AGENTSHIELD_PROJECT_ID=proj_xxx \
  -e BASE_URL=https://mcp.yourdomain.com \
  -v $(pwd)/.mcpi:/app/.mcpi:ro \
  my-mcp-server