Create AI Agents You Actually Own

Bootstrap MCP applications with cryptographic identity built-in. Get complete control over your agent's capabilities and permissions.

Quick Start

npx create-mcpi-app@latest my-agent
cd my-agent
npm run dev

Your agent now has its own cryptographic identity!

• Generated Identity: Ed25519 keys and DID automatically created
• Claim Ownership: Register at knowthat.ai to claim your agent
• Secure Operation: All responses cryptographically signed by your agent
• Permission Control: Delegate and revoke capabilities as needed

Command Line Options

npx create-mcpi-app [agent-name] [options]

Platform Options

Choose where to deploy your owned agent:

• -p, --platform <platform> - Target deployment platform (default: "standalone")
• standalone - Self-contained agent server
• cloudflare - Cloudflare Workers with Durable Objects and SSE support
• vercel - Vercel edge runtime with KV identity storage
• lambda - AWS Lambda with DynamoDB identity persistence
• nextjs - Next.js API routes with integrated identity
• express - Express.js server with identity middleware

General Options

• -t, --template <template> - Agent template (default: "typescript")
• --skip-install - Skip dependency installation
• --no-git - Skip git initialization
• --yes - Skip interactive prompts and use defaults
• --verbose - Detailed output during agent creation

Examples

# Create a standalone agent you can own
npx create-mcpi-app my-personal-agent

# Create a Cloudflare Workers MCP server
npx create-mcpi-app my-cloudflare-agent --platform cloudflare

# Quick creation without prompts
npx create-mcpi-app my-quick-agent --yes

Generated Project Structure

my-agent/
├── src/
│   ├── index.ts                   # Main agent server (~40 lines - super clean!)
│   ├── mcpi-runtime-config.ts      # Runtime configuration (~50 lines)
│   └── tools/                      # Your business logic only
│       └── greet.ts                # Example tool
├── wrangler.toml                   # Cloudflare Workers config
├── package.json                    # Dependencies
└── README.md                       # Quick start guide

Key Features:

• Next.js-Style Architecture: All framework complexity hidden in @kya-os/mcp-i-cloudflare
• Consent Pages: Server-hosted consent flow with XSS prevention
• Auto-Detection: Server URL automatically detected from requests
• Clean Code: Only your business logic visible - no implementation details

Platform-Specific Features

Cloudflare - Edge MCP Servers

• Global Edge Network: Deploy MCP servers to 300+ cities worldwide
• SSE & HTTP Streaming: Full MCP protocol support with Server-Sent Events
• Durable Objects: Built-in state management for MCP sessions
• Zero Cold Starts: Instant response times with Durable Objects
• KV Storage: Efficient nonce caching for security
• Consent Pages: Server-hosted consent flow with auto-detection
• XSS Prevention: Secure consent page rendering with CSP headers
• Proof Batching: Automatic proof submission with cron-based flushing

Proof Batching & Cron Jobs

MCP-I automatically batches proofs for efficient submission to AgentShield. Proofs are:

1. Batched within requests: When multiple tools are called, proofs are collected and submitted together
2. Auto-flush on batch size: When 10 proofs accumulate, they're automatically flushed
3. First proof immediate: The first proof is submitted immediately (not batched) for dashboard setup detection

Cron Configuration (Currently Disabled):

⚠️ Note: Cloudflare Workers cron triggers are currently experiencing API parsing issues that prevent deployment. The cron trigger is commented out by default in the generated wrangler.toml.

Proofs work correctly without cron because:

• First proof submits immediately (ensures dashboard setup detection)
• Proofs auto-flush when batch size is reached (default: 10 proofs)
• Cron is only needed for flushing small batches that haven't reached the size limit

If you want to enable cron-based flushing in the future, uncomment the section in wrangler.toml:

[[triggers.crons]]
cron = "*/5 * * * *"  # Every 5 minutes (recommended)

Note: If deployment fails with "Could not parse request body" when cron is enabled, this indicates a Cloudflare API issue. Keep cron commented out - proofs will still work correctly.

Verifying Proof Submission:

1. Check Cloudflare Worker logs for [ProofService] messages:

   • [ProofService] Initialized: - Service started successfully
   • [ProofService] Enqueuing proof - Proof added to batch queue
   • [ProofService] ✅ Proofs accepted - Proofs submitted successfully

2. View proofs in AgentShield dashboard:

   • Navigate to /proofs page for your project
   • Proofs appear within 5 minutes of tool execution

3. Verify tool discovery:

   • Navigate to /tools page
   • Tools are automatically discovered from proof submissions
   • Ensure MCP_SERVER_URL is set correctly (without /mcp suffix)

Vercel - Edge Identity

• Edge Runtime: Fast cold starts with cached identity context
• KV Storage: Secure identity persistence with Vercel KV
• Environment: Automatic identity configuration via environment variables
• Zero Config: Deploy with vercel --prod and identity works immediately

AWS Lambda - Serverless Identity

• Cold Start Optimized: Minimal initialization time with identity caching
• DynamoDB: Secure, scalable identity storage with DynamoDB
• IAM Policies: Pre-configured identity permissions and access control
• Serverless: Ready-to-deploy serverless framework configuration

Next.js - Full-Stack Identity

• API Routes: Identity-enabled API endpoints with automatic verification
• SSR Support: Server-side identity rendering and ownership verification
• Middleware: Request-level identity verification and permission checking
• Client Integration: Full-stack identity features for complete applications

Express - Identity Middleware

• Middleware Stack: Identity verification middleware for existing apps
• Flexible Routing: Identity-aware route handlers and permission checking
• Production Ready: Battle-tested middleware for production workloads
• Custom Auth: Extensible identity providers and authentication flows

Standalone

• File-based Persistence: Local identity storage
• Self-contained Deployment: No external dependencies
• Docker Ready: Containerized deployment support
• Process Management: PM2 and systemd configurations

Adding to Existing Projects

For existing Node.js/TypeScript projects, use the MCP-I CLI:

npm install -g @kya-os/cli
mcpi init

This automatically detects your framework (Next.js, Express, or standalone) and adds identity features without disrupting your existing codebase.

Getting Started with MCP-I

Step 1: Install MCP-I

cd my-existing-agent
npm install @kya-os/mcp-i

Step 2: Generate Identity

# Install CLI globally
npm install -g @kya-os/cli

# Initialize identity (development)
mcpi init

# Check identity status
mcpi check

Step 3: Integrate Identity

import { enableMCPIdentity } from "@kya-os/mcp-i";

const server = await enableMCPIdentity({
  name: "my-agent",
  description: "My AI agent with identity"
});

Troubleshooting

Common Issues

Identity Generation Fails

# Regenerate identity manually
mcpi rotate --force
mcpi init

Platform Detection Issues

# Force platform selection with verbose output
npx create-mcpi-app my-agent --platform vercel --verbose

Dependencies Issues

# Skip install and run manually
npx create-mcpi-app my-agent --no-install
cd my-agent && npm install

Identity File Missing

# Ensure identity exists before starting
npm run init
npm run dev

Debug Mode

# Enable verbose logging for troubleshooting
npx create-mcpi-app my-agent --verbose

# Check generated files without installation
npx create-mcpi-app my-agent --no-install --verbose

Next Steps

After creating your agent:

1. Start Development: npm run dev to start your agent locally
2. View Your Identity: Run mcpi check to see your agent's DID
3. Learn More: Read the full MCP-I documentation for advanced features
4. Deploy: Use platform-specific deployment guides in the MCP-I repo

Learn More

• MCP-I Documentation - Core framework and advanced features
• Model Context Protocol - Core protocol specification
• KYA-OS - Learn more about the KYA-OS ecosystem

License

This project is licensed under the MIT License - see the LICENSE file for details.