@kya-os/mcp-bri/README.md

Give your MCP server cryptographic identity in 2 lines of code

# @kya-os/mcp-i

Give your MCP server a decentralized identity (DID) in 2 lines of code. Build reputation, enable discovery, and future-proof your agent for the emerging identity ecosystem.

[![npm version](https://img.shields.io/npm/v/@kya-os/mcp-i.svg)](https://www.npmjs.com/package/@kya-os/mcp-i)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP-I Conformance](https://img.shields.io/badge/MCP--I-Level%202-green)](https://modelcontextprotocol-identity.io)

## Why Your MCP Server Needs This

**For MCP Server Developers:**

- 🆔 **Get a DID** - Your Agent gets a permanent, cryptographic identity
- 📈 **Build Reputation** - Every interaction is signed and verifiable
- 🔍 **Automatic Discovery** - Listed on registries as they adopt MCP-I
- 🔮 **Future-Proof** - Ready for the decentralized agent ecosystem

**For Directory Maintainers:**

- 🔌 **Easy Integration** - Become an MCP-I registry with our SDK
- ✅ **Verified Agents** - Only list agents with cryptographic proof
- 🌐 **Join the Standard** - Be part of the emerging identity layer

## The Vision

Your AI agent needs identity to:

- **Prove who it is** to other services (authentication)
- **Be discovered** by users and other agents (visibility)
- **Build reputation** through verified interactions (trust)
- **Access APIs** that require identity verification (capability)

## 🚨 IMPORTANT: API Call Behavior

**This package is designed to be spam-free:**

- **First run only**: API calls happen ONLY on first initialization
- **Persistent identity**: After first run, loads from disk with ZERO API calls
- **No spam on restarts**: Restart your server 1000 times = still zero API calls
- **Rate limited**: Built-in protection against accidental registry spam

[Read the full API behavior guide →](./API_BEHAVIOR.md)

## Installation

```bash
npm install @kya-os/mcp-i
```

## Quick Start

### 1. Zero Configuration (Recommended)

```typescript
import "@kya-os/mcp-i/auto";
// That's it! Your server now has cryptographic identity
```

### 2. With Configuration

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

await enableMCPIdentity({
  name: "Calendar Assistant",
  description: "AI agent for professional calendar management",
  repository: "https://github.com/your-org/calendar-assistant",
});
```

## Current State & Roadmap

**Today:**

- ✅ Your MCP server gets a DID (decentralized identifier)
- ✅ Every response is cryptographically signed
- ✅ Registered on KnowThat.ai registry
- ✅ Full MCP-I Level 2 conformance

**Coming Soon:**

- 🔜 Additional registry support as directories adopt MCP-I
- 🔜 Cross-registry reputation aggregation
- 🔜 Enhanced discovery features
- 🔜 Agent-to-agent secure communication

## What Happens Under the Hood

When you import this package:

1. **First Run Only**:

   - Generates Ed25519 cryptographic keypair
   - Registers with KnowThat.ai to obtain a DID
   - Saves identity to `.mcp-identity.json`
   - Total time: ~2 seconds

2. **Every Subsequent Run**:

   - Loads existing identity from disk
   - Zero API calls, instant startup
   - Maintains the same DID forever

3. **During Operation**:
   - Every response includes `_mcp_identity` field with cryptographic signature
   - Handles MCP-I challenge-response authentication automatically
   - Advertises identity capabilities to clients

## Example Response

After enabling MCP-I, all your server responses automatically include cryptographic signatures:

```json
{
  "content": [
    {
      "type": "text",
      "text": "Meeting scheduled for tomorrow at 2 PM"
    }
  ],
  "_mcp_identity": {
    "did": "did:web:knowthat.ai:agents:calendar-assistant",
    "signature": "0x3045...",
    "timestamp": "2025-01-06T10:00:00Z",
    "conformanceLevel": 2
  }
}
```

## Advanced Configuration

### Registry Support (Future-Ready)

As more directories adopt MCP-I, your agent will automatically be discoverable across the ecosystem:

```typescript
await enableMCPIdentity({
  name: "My Agent",
  registries: "verified", // default
  // Currently registers with KnowThat.ai
  // Additional registries will be supported as they adopt MCP-I
});
```

**Note for Directory Maintainers:** Want to add your directory as a supported registry? [Contact us](https://github.com/orgs/modelcontextprotocol-identity/discussions/new?category=mcp-i-directories) to discuss integration.

### Custom DID Host

For enterprises who want to host their own DID:

```typescript
await enableMCPIdentity({
  name: "Enterprise Agent",
  didHost: "company.com", // Creates did:web:company.com:agents:...
});
```

Note: The Agent's did must discoverable via company.com/.well-known/did.json

### Edit Your Agent Profile

Only you can edit your agent's profile, thanks to cryptographic proof:

```typescript
const identity = await enableMCPIdentity();

// Get a signed edit URL
const editUrl = await identity.requestEditAccess();
console.log("Edit your agent at:", editUrl);
// https://knowthat.ai/agents/edit?did=...&timestamp=...&signature=...
```

## Key Benefits

**Immediate Benefits:**

- 🛡️ **Cryptographic Identity**: Every response is signed with Ed25519
- 🆔 **Permanent DID**: Your agent gets a decentralized identifier that you control
- 🔐 **Impersonation Protection**: Nobody can pretend to be your agent
- ✅ **Verification Ready**: Cryptographic proof of authenticity

**Future Benefits (as ecosystem grows):**

- 🔍 **Multi-Registry Discovery**: Automatically listed as directories adopt MCP-I
- 📈 **Reputation Building**: Verifiable interaction history across platforms
- 🚀 **Priority Access**: Identity-aware APIs will offer higher rate limits
- 🏆 **Trust Badges**: Stand out as an early adopter of decentralized identity

## How MCP-I Works

```mermaid
sequenceDiagram
    participant User
    participant Client as AI Client
    participant Agent as Your MCP Server
    participant API as Protected API

    User->>Client: "Book a meeting"
    Client->>Agent: MCP request
    Note over Agent: Signs response with private key
    Agent->>Client: Response + _mcp_identity
    Client->>API: Forward request with identity
    API->>API: Verify signature
    API->>Client: Authorized response
    Client->>User: "Meeting booked!"
```

## Files Created

After initialization, you'll see these files in your project root:

```
.mcp-identity.json    # Your agent's identity (⚠️ Contains private key!)
```

The file contains:

```json
{
  "did": "did:web:knowthat.ai:agents:your-agent",
  "publicKey": "base64-encoded-public-key",
  "privateKey": "base64-encoded-private-key", // Keep this secret!
  "agentId": "uuid",
  "agentSlug": "your-agent-slug",
  "registeredAt": "2025-05-11T12:12:00Z",
  "didHost": "knowthat.ai",
  "registry": {
    "name": "knowthat.ai",
    "status": "active",
    "url": "https://knowthat.ai/agents/your-agent-slug"
  }
}
```

## Security Best Practices

- 🔐 **Private keys never leave your server** - stored locally only
- ✍️ **Ed25519 signatures** - cryptographically secure
- 🛡️ **Replay protection** - timestamps and nonces prevent attacks
- 🔑 **Add `.mcp-identity.json` to .gitignore** - contains private key!

## Troubleshooting

### "Rate limit exceeded"

- Wait 1 hour before retrying
- Each IP can register 10 agents/hour on KnowThat.ai

### Agent not showing as verified

- Verification can take up to 5 minutes
- Check https://knowthat.ai/agents/YOUR-AGENT-SLUG

### Lost your identity file?

- Unfortunately, DIDs cannot be recovered
- You'll need to create a new identity
- Previous registrations cannot be updated

## API Reference

### `enableMCPIdentity(options?)`

Main function to enable identity for your MCP server.

**Options:**

- `name` (string): Your agent's display name
- `description` (string): What your agent does
- `repository` (string): GitHub repo URL
- `didHost` (string): Custom DID host (default: "knowthat.ai")

**Returns:** `Promise<MCPIdentity>`

### `MCPIdentity` class

**Methods:**

- `sign(message)`: Sign a message with your private key
- `verify(message, signature)`: Verify a signature
- `respondToChallenge(challenge)`: Handle MCP-I authentication
- `signResponse(response)`: Add identity to any response
- `requestEditAccess()`: Get edit URL for your agent profile
- `getRegistryStatus()`: Check registration status

## FAQ

**Q: Is this package affiliated with Anthropic?**  
A: No, this is a community package implementing the MCP-I specification.

**Q: Can I use this without MCP?**  
A: Yes! The `MCPIdentity` class can be used standalone for any identity needs.

**Q: What happens if KnowThat.ai is down?**  
A: After initial registration, your agent works offline. The DID is self-contained.

**Q: Can I change my agent's name later?**  
A: Yes, use `requestEditAccess()` to get an edit URL with cryptographic proof.

**Q: Why only KnowThat.ai registry right now?**  
A: We're building the ecosystem! As directories adopt MCP-I, your agent will automatically be discoverable across all of them.

**Q: I run a directory. How can I support MCP-I?**  
A: [Contact us](https://github.com/orgs/modelcontextprotocol-identity/discussions/new?category=mcp-i-directories) to discuss integration. We're actively seeking directory partners.

**Q: Is this production-ready?**  
A: Yes, but currently in beta. The API may change before 1.0.

## Join the Identity Revolution

**MCP Server Developers:** Give your server an identity today. Be discoverable, build reputation, and future-proof your agent for the emerging ecosystem.

```bash
npm install @kya-os/mcp-i
```

**Directory Maintainers:** Want to be part of the decentralized identity ecosystem? MCP-I enables you to list only verified agents with cryptographic proof of identity. [Let's talk integration →](https://github.com/orgs/modelcontextprotocol-identity/discussions/new?category=mcp-i-directories)

## License

MIT