Compatibility & Legacy
How MCP-I interoperates with legacy identity systems and supports progressive adoption.
Compatibility & Legacy
Key Takeaways
- MCP-I is designed to work alongside OAuth2, SAML, and JWT-based systems - You can progressively adopt DIDs and DelegationCredentials without replacing existing identity tools - Mapping tools exist to link legacy user IDs to DIDs
- Legacy agents (CLIs, HTTP clients) can be supported using verifiers and header-wrappers - Upgrade paths allow phased migration from static IDs to delegated, revocable credentials
Why Compatibility Matters
MCP-I is designed to enhance identity, not replace it. It supports gradual adoption, works alongside OAuth and SAML, and bridges traditional and decentralized identity stacks.
Key Design Principles
- Incremental Adoption: Start with agent identity (Level 1), add user delegation later
- Interoperability: Can be layered on top of existing API gateways, identity providers, or edge infrastructure
- Backwards-Compatible: Works with JWTs, session cookies, legacy user IDs
- Schema-Agnostic: Supports any VC schema your verifier is configured to understand
Bridging Legacy Identity
| Legacy Model | Compatible Pattern |
|---|---|
| OAuth2 (Access Token) | Map token scope → DelegationCredential.scope |
| SAML Assertion | Extract user attributes → Include in VC claims |
| API Key | Replace with scoped DID-based credential |
| Session Cookie | Treat session as a short-lived credential wrapper |
| User ID Mapping | Link userId ↔ DID via mapping registry or SDK method |
You can create a Verifiable Credential that wraps or translates your existing identity claims.
Working With JWTs
You can issue VCs that:
- Embed a JWT as a claim
- Assert VC with a JWT signature
- Map
sub,aud, andexpfields to standard VC structure
This allows you to plug MCP-I into existing backend logic without full rewrites.
Legacy Identity Mapping
MCP-I supports customer-to-DID mapping through:
- SDK utilities like
getDidByCustomerId(...) - DID-User Registries
- Alias claims in identity credentials
This enables support for users who authenticate through traditional identity systems (Auth0, Firebase, etc.)
Legacy Agent Compatibility
You can issue credentials or wrap identifiers for:
- HTTP clients (API tokens)
- CLI tools (machine identity)
- Non-MCP-aware agents (via proxies or signed headers)
The edge verifier can validate these and convert them to a valid DelegationCredential.
Upgrade Flow Diagram
This shows how an existing identity record can be bridged into MCP-I without breaking legacy systems.
Recommended Upgrade Path
| Phase | Action |
|---|---|
| Step 1 | Give agents static DIDs (Level 1) |
| Step 2 | Link users to DIDs (mapping or DID issuance) |
| Step 3 | Introduce delegation VCs |
| Step 4 | Enable revocation and audit logs |
| Step 5 | Gradually deprecate legacy tokens/cookies in favor of scoped VCs |
Related Topics
MCP-I is designed to gracefully extend legacy environments without requiring a full rewrite. Many teams may continue using OAuth, OIDC, or JWT-based systems.
SDK-Based Fallback Example
The KYA-OS SDK supports interoperability between DIDs and customer-facing IDs:
const legacyUserId = "user_123";
const userDid = await kyaOsClient.ensureUserHasDid(legacyUserId);
This allows you to treat legacy IDs as DID-compatible without changing your underlying user database.
DID Introduction Pathways
When bridging a legacy system to MCP-I:
- Issue a DID for each user on demand (lazy creation)
- Use delegation credentials to scope access without touching existing auth logic
- Introduce audit-backed revocation gradually using Edge Verification Guide
For full setup examples, see the Quick Start Guide.