Create AI Agents You Actually Own

Bootstrap XMCP applications with cryptographic identity. Register them with knowthat.ai, and maintain complete control over your agent's capabilities and permissions.

Quick Start

npx create-xmcpi-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-xmcpi-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
• 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")
• --no-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-xmcpi-app my-personal-agent

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

Generated Project Structure

my-agent/
├── src/
│   ├── index.ts                    # Main agent server with identity
│   ├── generate-identity.ts        # Cryptographic identity generation
│   ├── identity-utils.ts           # Signing, verification, and ownership utilities
│   ├── ensure-identity.ts          # Automatic identity initialization
│   ├── generated-identity.json     # Your agent's identity (keep secure!)
│   └── tools/
│       ├── greet.ts               # Example tool with identity integration
│       ├── identity-info.ts       # Display agent identity information
│       ├── sign-message.ts        # Sign messages with agent's key
│       └── verify-signature.ts    # Verify ownership and signatures
├── package.json                    # Dependencies including xmcp-i
├── tsconfig.json                   # TypeScript configuration
├── .env.example                    # Environment variables for identity
├── .gitignore                      # Includes identity security rules
├── .eslintrc.json                  # Code quality configuration
└── README.md                       # Agent-specific documentation

Security Note: The generated-identity.json file contains your agent's private key. This file is automatically added to .gitignore and should never be shared or committed to version control.

Platform-Specific Features

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 init command:

npx init-xmcp-i@latest

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

Upgrading from create-xmcp-app

Upgrade your existing XMCP agents to have ownership capabilities:

Step 1: Install xmcp-i

cd my-existing-agent
npm install xmcp-i

Step 2: Generate Identity

npx tsx generate-identity.ts

Or generate inline:

// generate-identity.ts
import { generateIdentity } from 'xmcp-i/generate';
import fs from 'fs';

const identity = generateIdentity();
fs.writeFileSync('src/generated-identity.json', JSON.stringify(identity, null, 2));
console.log('Identity generated:', identity.did);

Step 3: Update Imports

Update your existing code imports:

// Before
import { createXMCPServer } from 'xmcp';

// After
import { createXMCPServer } from 'xmcp-i';

Troubleshooting

Common Issues

Identity Generation Fails

# Regenerate identity manually
cd my-agent/src
npx tsx generate-identity.ts

Platform Detection Issues

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

Dependencies Issues

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

Identity File Missing

# Ensure identity exists before starting
npm run ensure-identity
npm run dev

Debug Mode

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

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

Next Steps

After creating your agent:

1. Start Development: npm run dev to start your agent locally
2. Claim Ownership: Visit knowthat.ai to register your agent's DID
3. Learn More: Read the full xmcp-i documentation for advanced features
4. Deploy: Use platform-specific deployment guides in the xmcp-i repo

Learn More

• XMCP-I Documentation - Core framework and advanced features
• Model Context Protocol - Core protocol specification

License

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