Goal

Deploy a fully configured MCP-I (Model Context Protocol with Identity) server using Checkpoint's managed deployment pipeline. By the end of this cookbook, you'll have:

A GitHub repository with production-ready MCP-I server code
Automatic deployment to Cloudflare Workers
Agent identity (DID) registered with Know That AI
Dashboard integration for monitoring delegations and proofs
Optional Claude/Anthropic API integration

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

Prerequisites

A Checkpoint account
A GitHub account with the Checkpoint GitHub App installed
A Cloudflare account (free tier works)
(Optional) Anthropic API key for Claude integration

Time Estimate

15 minutes

What Gets Created

When you complete this cookbook, Checkpoint will create:

Component	Description
GitHub Repository	Private repo with MCP-I server source code
Cloudflare Worker	Edge deployment of your MCP-I 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
Know That AI Profile	Public agent profile (optional)

Steps

Connect GitHub

If you haven't already connected GitHub:

Go to your Checkpoint dashboard
Navigate to Settings → Integrations
Click Connect GitHub
Install the Checkpoint GitHub App to your account or organization
Select which repositories to grant access (or all repositories)

Checkpoint needs repository access to create the MCP-I server repo and configure secrets.

Start the Deployment Wizard

In your dashboard, navigate to Projects → New Project
Select Govern (MCP-I Server)
Click Deploy MCP-I Server

You'll see the deployment configuration form.

Configure Your Server

Fill in the deployment configuration:

Field	Required	Description	Example
Project Name	Yes	Becomes GitHub repo name. Lowercase, alphanumeric, hyphens only.	`my-ai-assistant`
Agent Name	Yes	Human-readable display name for the agent	`My AI Assistant`
Agent Description	No	Purpose of the agent (shown in consent screens)	`Helps users manage their calendar`

Optional Integrations:

Field	Required	Description
Anthropic API Key	No	Enables Claude integration in your worker
Cloudflare API Token	No	For automatic deployment (can add later)
Cloudflare Account ID	No	Required with API token

Don't have Cloudflare credentials yet? Skip them now and add them later as GitHub Secrets.

Watch the Deployment Pipeline

Click Deploy to start the pipeline. You'll see real-time progress through 9 steps:

Verify GitHub — Confirms app installation and repo name availability
Create Project — Creates Checkpoint project for monitoring
Generate API Key — Creates encrypted API key for the worker
Register Identity — Generates DID and registers with Know That AI
Scaffold Files — Generates MCP-I server source code
Create Repository — Creates private GitHub repository
Commit Files — Pushes code to the repository
Add Secrets — Configures GitHub Secrets
Configure Gateway — Sets up routing (if applicable)

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 Know That 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 didn't provide Cloudflare credentials during setup:

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 Checkpoint dashboard, select your new project
Go to Control Access → Tools
Click Add Tool

Example: File Read Tool

name: read_file
display_name: Read File
description: Reads content from a file
scopes:
  - files:read
require_delegation: true

Example: Send Email Tool

name: send_email
display_name: Send Email
description: Sends an email on behalf of the user
scopes:
  - email:send
require_delegation: true
sensitive: true

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          # MCP-I server entry point
├── wrangler.toml          # Cloudflare Workers config
├── package.json
├── tsconfig.json
└── .github/
    └── workflows/
        └── deploy.yml    # Auto-deploy on push

Key file: src/index.ts

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,
    },
    admin: {
      enabled: true,
      apiKey: env.ADMIN_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);
  },
};

GitHub Secrets Created:

Secret	Purpose
`AGENTSHIELD_API_KEY`	Worker → Checkpoint API
`MCP_IDENTITY_PRIVATE_KEY`	Agent's Ed25519 private key
`ANTHROPIC_API_KEY`	Claude API (if provided)
`CLOUDFLARE_API_TOKEN`	Deployment (if provided)
`CLOUDFLARE_ACCOUNT_ID`	Deployment (if provided)

Adding Custom Tools

Extend your server with custom tools:

// src/tools/calendar.ts
import { Tool, ToolResult } from '@kya-os/mcp-i-cloudflare';

export const getCalendarEvents: Tool = {
  name: 'get_calendar_events',
  description: 'Retrieves upcoming calendar events',
  scopes: ['calendar:read'],
  parameters: {
    type: 'object',
    properties: {
      days: {
        type: 'number',
        description: 'Number of days to look ahead',
        default: 7,
      },
    },
  },
  handler: async (params, context): Promise<ToolResult> => {
    const { days = 7 } = params;

    // Your calendar API integration
    const events = await fetchCalendarEvents(context.user, days);

    return {
      success: true,
      data: events,
    };
  },
};

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

// In your server config
tools: [getCalendarEvents],

Verify It's Working

Dashboard Verification

Go to Control Access → Delegations — See active delegations
Go to Proofs — Monitor proof verification activity
Go to Analytics — View request patterns

API Health Check

curl https://your-worker.your-account.workers.dev/__health
# Should return: { "status": "ok", "did": "did:key:z6Mk..." }

Know That 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 an MCP-I 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 MCP-I Migration
Configure auth methods	Auth Methods Reference
Understand delegations	Delegations

Govern: Dashboard Deploy (Managed)