npm package: @kya-os/create-mcpi-app
Description: Scaffold a new MCP-I application
Latest version: 1.9.35

<div align="center">
  <a href="https://github.com/modelcontextprotocol-identity/xmcp-i">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/modelcontextprotocol-identity/xmcp-i/main/assets/mcp-i-logo-dark.png">
      <img alt="MCP-I logo" src="https://raw.githubusercontent.com/modelcontextprotocol-identity/xmcp-i/main/assets/mcp-i-logo-light.png" height="128">
    </picture>
  </a>
  <h1>create-mcpi-app</h1>

<a href="https://github.com/modelcontextprotocol-identity/xmcp-i"><img alt="MCP-I" src="https://img.shields.io/badge/MCP--I-000000.svg?style=for-the-badge&labelColor=000"></a>
<a href="https://www.npmjs.com/package/@kya-os/create-mcpi-app"><img alt="NPM version" src="https://img.shields.io/npm/v/@kya-os/create-mcpi-app.svg?style=for-the-badge&labelColor=000000"></a>
<a href="https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/license.md"><img alt="License" src="https://img.shields.io/npm/l/@kya-os/create-mcpi-app.svg?style=for-the-badge&labelColor=000000"></a>

</div>

## 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

```bash
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

```bash
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

```bash
# 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`:

```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:

```bash
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

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

### Step 2: Generate Identity

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

# Initialize identity (development)
mcpi init

# Check identity status
mcpi check
```

### Step 3: Integrate Identity

```javascript
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

```bash
# Regenerate identity manually
mcpi rotate --force
mcpi init
```

#### Platform Detection Issues

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

#### Dependencies Issues

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

#### Identity File Missing

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

### Debug Mode

```bash
# 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](https://github.com/modelcontextprotocol-identity/xmcp-i) for advanced features
4. **Deploy**: Use platform-specific deployment guides in the MCP-I repo

## Learn More

- [MCP-I Documentation](https://github.com/modelcontextprotocol-identity/xmcp-i) - Core framework and advanced features
- [Model Context Protocol](https://modelcontextprotocol.io) - Core protocol specification
- [KYA-OS](https://kya-os.com) - Learn more about the KYA-OS ecosystem

## License

This project is licensed under the MIT License - see the [LICENSE](https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/license.md) file for details.