This document lays out the problem, our solution, how the model works, integration options for developers, the technical architecture, and a practical roadmap.
Today’s AI ecosystem faces a three-way trust and access problem:
These issues lead to poor user experiences, operational cost, and limited AI utility.
CirtusAI is a trust layer that addresses these problems by providing:
Benefits:
flowchart LR
%% Centered CirtusAI with radial connections to User, Agent, and Service
style CirtusAI fill:#0f1720,stroke:#2b3940,stroke-width:2px
CirtusAI["CirtusAI Platform<br/>Trust, VAP, CapTokens, Connectors"]
User((User))
Agent((AI Agent))
Service((Third-Party Service))
User ---|"Grants approvals / Policies"| CirtusAI
Agent ---|"Requests capabilities / Intents"| CirtusAI
Service ---|"Verifies VAP & receipts"| CirtusAI
%% Mirror Interaction Comparison Summary
User -.->|"Control, consent, audit trail"| Agent
Agent -.->|"Autonomy, dedicated assets, reduced auth friction"| User
Agent -->|"Audited actions, VAP-backed calls"| Service
Service -->|"Monetization: engagement, attribution, native ads"| Agent
Service -->|"Receives signed receipts, provenance"| User
%% Secondary annotations pulled from table
subgraph Notes [Interaction Summary]
direction TB
N1["User ↔ AI: SDK/MCP, Approval System, Separate AI assets"]
N2["AI ↔ Services: VAP certs, connectors, reliable API access"]
N3["Services ↔ Users: Monetization, attribution, partner SLAs"]
end
CirtusAI --- N1
CirtusAI --- N2
CirtusAI --- N3
click CirtusAI "#" "CirtusAI platform (center)"
Traditional interaction between users and AI agents requires users to repeatedly provide credentials, manually handle authentication, and maintain constant oversight of AI operations. This creates friction and limits AI autonomy.
CirtusAI changes this model by routing AI agents’ requests through the platform. Agents connect either via language/tool SDKs or via the Model Context Protocol (MCP) bridge. The platform evaluates policy and reputation, issues capability tokens or approval requests, and executes actions with platform-managed assets when necessary. Users grant scoped permissions through the Approval System; approvals are cryptographically signed, time-limited, and auditable.
The introduction should mention the SDK and MCP as high-level integration paths. Detailed API shapes, SDK design, and MCP wire format are shown in the Technical Implementation section;
sequenceDiagram
participant User as User
participant Agent as AI Agent
participant SDK as SDK / Client
participant MCP as MCP Bridge
participant Platform as CirtusAI Backend
participant Assets as AI Assets
participant Approval as Approval System
Note over Agent,Platform: Two integration paths
Agent->>SDK: 1. Invoke action via SDK (client-side)
Agent->>MCP: 1b. Or send MCP call (tool bridge)
SDK->>Platform: 2. API request (capability request / intent)
MCP->>Platform: 2b. MCP message (capability request / intent)
Platform->>Platform: 3. Evaluate policy & reputation
alt Approval required
Platform->>Approval: 4. Create ApprovalRequest
Approval->>User: 5. Send approval notification (mobile/web)
User-->>Approval: 6. Approve / Deny
Approval->>Platform: 7. Approval result (signed receipt)
end
Platform->>Assets: 8. Execute using AI assets OR proxy to user account
Assets->>Platform: 9. External call result (provider response)
Platform->>Agent: 10. Return result + ActionReceipt
Note over User,Agent: Audit trail and receipts persisted
High-level sequence showing SDK and MCP integration paths, the platform’s policy/approval evaluation, and execution using platform-managed assets (or proxying to user accounts when required). The Technical Implementation section contains full SDK and MCP specifications.
See the Technical Implementation section for integration details, API shapes, and SDK guidance.
Benefits for Users:
Benefits for AI Agents:
AI agents traditionally rely on brittle browser automation, screen scraping, and credential spoofing to interact with third-party services. This leads to frequent blocking, rate limiting, and security concerns for both services and users.
sequenceDiagram
participant AIAgent as AI Agent
participant CirtusAI as CirtusAI Platform
participant VAP as VAP Engine
participant Service as Third Party Service
participant Assets as AI Assets
rect rgb(20, 28, 36)
Note over AIAgent,Service: Traditional AI-Service Interaction
AIAgent->>Service: Browser automation request
Service-->>AIAgent: ❌ Blocked/Rate limited
AIAgent->>Service: Retry with different headers
Service-->>AIAgent: ❌ Detected as bot
end
rect rgb(20, 28, 36)
Note over AIAgent,Service: CirtusAI Enhanced Integration
AIAgent->>CirtusAI: Request service access
CirtusAI->>VAP: Generate verification certificate
VAP->>CirtusAI: VAP certificate with identity/reputation
CirtusAI->>Assets: Provision AI-specific credentials
Assets->>Service: API call with VAP certificate
Service->>Service: Verify certificate authenticity
Service-->>Assets: ✅ Trusted API response
Assets->>CirtusAI: Success + data
CirtusAI->>AIAgent: Formatted response
end
AI agents struggle with traditional service integration due to anti-bot measures, while CirtusAI provides verified identity and dedicated access channels.
Traditional Problems:
CirtusAI Solutions:
Services struggle to distinguish legitimate AI operations from malicious bots, leading to overly restrictive policies that block beneficial AI usage while failing to prevent actual threats.
In addition, third-party services prioritize monetization: user attention, engagement, ad impressions, and high-quality conversion events drive revenue. To be a valued partner, CirtusAI must demonstrate capabilities that increase measurable revenue and preserve — or enhance — the service’s monetization channels.
CirtusAI can offer potential partner-facing features including:
– TBC
Benefits for Third Party Services:
Benefits for Users:
| Interaction | Traditional Issues | CirtusAI Solution |
|---|---|---|
| User ↔ AI | Manual auth, limited autonomy, privacy risks | SDK / MCP integration, AI identity delegation, approval system, separate AI assets |
| AI ↔ Services | Browser automation, blocking, unreliable access | API integration, VAP certificates, dedicated credentials, provenance receipts for ad/tracking integrity |
| Services ↔ Users | Overly restrictive bot detection, poor UX; loss of monetization opportunities | Partner monetization features: engagement SLAs, consent-forward monetization, analytics & attribution, referral/revenue-sharing, native ad support |
A compact summary of how the pieces fit together:
flowchart LR
U["User"]
FE["Frontend (Web/Mobile)"]
SDK["SDK / MCP"]
PL["Platform (CirtusAI Backend)"]
AG["AI Agent"]
AS["AI Assets / Connectors"]
VAP["VAP Engine / Certificates"]
SRV["Third-Party Service"]
U -->|"UI: grant approvals, view receipts"| FE
FE -->|"submit capability request"| SDK
SDK -->|"POST /v1/capabilities/request"| PL
AG -->|"request capabilities / intents"| SDK
PL -->|"evaluate policy & reputation"| VAP
PL -->|"issue signed capability token / VAP"| SDK
SDK -->|"deliver token + ActionReceipt"| AG
AG -->|"use provisioned AI assets / connectors with VAP"| AS
AS -->|"call with VAP and receipts"| SRV
SRV -->|"response / provider result"| AS
AS -->|"forward result + ActionReceipt"| PL
PL -->|"persist audit log / receipts"| U
%% Clarifying note nodes (non-intrusive, plain text)
note_left(["Note: The platform issues capability tokens and VAP certificates, maintains policies and audit logs, and provisions AI-specific assets, but it does NOT directly perform outbound calls to third-party services on behalf of users."])
note_right(["AI Agents perform outbound calls using their provisioned AI assets; all external interactions are initiated by agents and accompanied by VAPs and signed receipts."])
note_left --- PL
note_right --- AG
Notes: Users grant approvals through the frontend which submits signed approval data to the backend; CirtusAI issues tokens and VAP certificates but does not itself call third-party services — the AI agent performs outbound calls using its own provisioned assets and presents VAP certs for verification. ActionReceipts and VAP certs are cryptographically signed by the platform and may be forwarded to external parties for provenance and monetization.
The Model Context Protocol (MCP) allows existing AI tools like Claude Desktop, GitHub Copilot, and ChatGPT to seamlessly access CirtusAI’s AI identity services and capability-based access control without any modifications to their existing workflows. The MCP server acts as a transparent bridge that handles capability token lifecycle management behind the scenes.
The MCP server implements the complete capability token workflow transparently:
tools/list, the MCP server queries the CirtusAI platform for available capabilities and transforms them into MCP tool definitionstools/call, the MCP server automatically requests the appropriate capability token from the platformtools/call with capability ID and parametersThe MCP server acts as a transparent proxy for capability token operations, allowing unmodified AI tools to benefit from CirtusAI’s security model without requiring integration changes.
Token Caching Strategy:
Approval Flow Handling:
sequenceDiagram
participant AITool as AI Tool
participant MCP as MCP Server
participant Backend as CirtusAI Backend
participant Approval as Approval Service
AITool->>MCP: tools/call: send_email
MCP->>Backend: POST /v1/capabilities/request
Backend->>Backend: Policy evaluation
alt Approval Required
Backend->>Approval: Create approval request
Backend->>MCP: 202 Approval Required
MCP->>MCP: Wait for approval (async)
Approval-->>Backend: User approves
Backend->>MCP: Capability token issued
else Auto-Approved
Backend->>MCP: 200 Capability token
end
MCP->>Backend: POST /v1/actions/execute
Backend->>MCP: ActionReceipt
MCP->>AITool: MCP response (formatted)
For AI developers, CirtusAI transforms complex multi-week integration processes into simple, secure API calls. The SDK provides a streamlined interface that abstracts capability token management, approval workflows, and external service integration while maintaining enterprise-grade security and auditability.
Traditional approach problems:
CirtusAI approach advantages:
Developer Experience Philosophy: The SDK follows the principle of “simple by default, powerful when needed.” Common workflows require minimal code (3-5 lines), while advanced use cases provide full control over capability discovery, token caching, approval handling, and error recovery.
The SDK implements a capability-based access model with three primary abstractions:
Value to developers: The SDK abstracts complex capability token management while providing full control when needed. Developers get enterprise-grade security, audit trails, and compliance features without sacrificing development speed or simplicity.
The SDK provides for capability token management. All external service integrations use platform-issued tokens rather than storing provider credentials in client applications.
Key SDK Principles:
flowchart TD
%% Developer Entry Point
Dev[AI Developer<br/>Wants AI Identity]
%% SDK Installation
Install[Install CirtusAI SDK<br/>pip install cirtusai<br/>Quick Setup]
%% Integration Steps (Vertical) - Updated with Capability Tokens
subgraph Integration [SDK Integration Process]
direction TB
Init[Initialize Client<br/>client = CirtusAI<br/>API Key Setup]
Discover[Discover Capabilities<br/>client.discover_capabilities<br/>Capability Catalog]
Request[Request Capability<br/>capability_token<br/>Auto or Manual Approval]
Execute[Execute Action<br/>client.execute_action<br/>With Capability Token]
Receipt[Receive Receipt<br/>ActionReceipt<br/>Audit Trail]
end
%% Backend Processing (Vertical) - Enhanced for Capability Tokens
subgraph Backend [CirtusAI Backend Processing]
direction TB
API[REST API Gateway<br/>Request Handling]
Identity[Identity Manager<br/>DID Creation]
CapMgr[Capability Manager<br/>Token Lifecycle]
Trust[Trust Engine<br/>Policy Evaluation]
Approval[Approval Service<br/>User Consent]
Executor[Action Executor<br/>Platform Connectors]
end
%% AI Resources (Vertical)
subgraph AIAssets [AI Dedicated Assets]
direction TB
Email[AI Email Account<br/>[email protected]<br/>Independent Inbox]
Wallet[AI Crypto Wallet<br/>0x123...abc<br/>Blockchain Assets]
Identity[AI Identity Cert<br/>DID Verification<br/>Platform Trust]
end
%% External Integration (Vertical) - Enhanced with VAP
subgraph External [External Platform Integration]
direction TB
ExternalServices[External Services]
end
%% Capability Token Flow (New)
subgraph TokenFlow [Capability Token Lifecycle]
direction TB
TokenReq[Token Request<br/>caps + constraints]
PolicyEval[Policy Evaluation<br/>Trust + Reputation]
TokenIssue[Token Issuance<br/>Signed JWT/COSE]
TokenExecute[Token Execution<br/>Platform Connector]
AuditLog[Audit Logging<br/>ActionReceipt]
end
%% Flow connections
Dev --> Install
Install --> Integration
Integration --> Backend
Backend --> TokenFlow
TokenFlow --> AIAssets
TokenFlow --> ExternalServices
AIAssets --> ExternalServices
%% Detailed Token Flow
Request --> TokenReq
TokenReq --> PolicyEval
PolicyEval --> TokenIssue
Execute --> TokenExecute
TokenExecute --> AuditLog
AuditLog --> Receipt
%% Styling
classDef devStyle fill:#111316,stroke:#2b3940,stroke-width:2px
classDef sdkStyle fill:#111316,stroke:#274251,stroke-width:2px
classDef backendStyle fill:#0f1720,stroke:#2b3940,stroke-width:2px
classDef assetStyle fill:#10161a,stroke:#3a2b1a,stroke-width:2px
classDef externalStyle fill:#16171a,stroke:#3a2630,stroke-width:2px
classDef tokenStyle fill:#141518,stroke:#3b2f20,stroke-width:3px
class Dev devStyle
class Integration,Install sdkStyle
class Backend,API,Identity,CapMgr,Trust,Approval,Executor backendStyle
class AIAssets,Email,Wallet,Identity assetStyle
class ExternalServices externalStyle
class TokenFlow,TokenReq,PolicyEval,TokenIssue,TokenExecute,AuditLog tokenStyle
The Capability Manager orchestrates the complete lifecycle of capability tokens, from initial request through execution and audit trail generation. It serves as the central coordination point for all capability-based operations.
Core Responsibilities:
The Permissions Engine is the core decision-making component that evaluates capability requests, enforces policies, and determines approval requirements. It implements a multi-layered evaluation system with configurable policies, real-time risk assessment, and adaptive trust scoring.
The Permissions Engine evaluates capability requests through a structured decision flow that maps AI identity, requested capabilities, and context to policy rules, returning one of three outcomes: auto-approve, require-approval, or deny.
Input Parameters:
ai_identity: DID of the requesting AI agentrequested_caps: Array of capability identifiers with constraintscontext: Request metadata (timestamp, source IP, device fingerprint, purpose)Evaluation Logic:
Token Structure: Approved capability tokens are JWT/COSE signed objects containing:
jti: Unique token identifier for revocationiss: CirtusAI platform issuersub: AI DID (subject)caps: Array of granted capabilities with constraintsconstraints: Execution limits (time windows, usage quotas, allowed recipients)iat/exp: Issuance and expiration timestamps (typically 5-60 minutes TTL)sig: Platform signature for verificationStorage and TTL:
flowchart LR
PolicyEval[Policy Evaluation<br/>Identity + Caps + Context]
TokenIssue[Token Issuance<br/>Signed JWT/COSE]
AuditLog[Audit Logging<br/>Decision + Metadata]
Execution[Action Execution<br/>Platform Connector]
PolicyEval --> TokenIssue
TokenIssue --> AuditLog
TokenIssue --> Execution
AuditLog --> Execution
classDef evalStyle fill:#0f1720,stroke:#274251,stroke-width:2px
classDef tokenStyle fill:#141518,stroke:#3b2f20,stroke-width:2px
classDef auditStyle fill:#0f1720,stroke:#2b3940,stroke-width:2px
classDef execStyle fill:#111316,stroke:#274251,stroke-width:2px
class PolicyEval evalStyle
class TokenIssue tokenStyle
class AuditLog auditStyle
class Execution execStyle
flowchart TD
%% === API GATEWAY LAYER ===
subgraph Gateway [API Gateway Layer]
direction TB
REST[REST API<br/>FastAPI<br/>Port 8000]
MCP[MCP Server<br/>Standard Protocol<br/>Port 3000]
WebSocket[WebSocket<br/>Real-time Updates<br/>Port 8001]
end
%% === CORE SERVICES LAYER ===
subgraph Core [Core Services Layer]
direction TB
Auth[Authentication<br/>JWT + API Keys<br/>User Sessions]
Identity[Identity Service<br/>DID Management<br/>AI Registration]
CapMgr[Capability Manager<br/>Token Lifecycle<br/>Policy Enforcement]
PermEngine[Permissions Engine<br/>Risk Assessment<br/>Policy Evaluation]
Assets[Asset Manager<br/>Email/Wallet<br/>Resource Allocation]
Trust[Trust Engine<br/>Reputation Scoring<br/>VAP Certificates]
Approval[Approval System<br/>User Consent<br/>Workflow Engine]
Executor[Action Executor<br/>Platform Connectors<br/>Receipt Generation]
end
%% === MESSAGE QUEUE LAYER ===
subgraph Queue [Message Queue Layer]
direction TB
RabbitMQ[RabbitMQ<br/>Message Broker<br/>Queue Management]
Celery[Celery Workers<br/>Background Tasks<br/>Email/Crypto Jobs]
CeleryBeat[Celery Beat<br/>Scheduled Tasks<br/>Trust Score Updates]
end
%% === DATA LAYER ===
subgraph Data [Data Layer]
direction TB
Postgres[PostgreSQL<br/>Main Database<br/>ACID Transactions]
Redis[Redis<br/>Cache + Sessions<br/>Real-time Data]
Blockchain[Blockchain<br/>DID Registry<br/>Immutable Records]
Files[File Storage<br/>Media + Logs<br/>S3/MinIO]
end
%% === EXTERNAL SERVICES ===
subgraph External [External Services]
direction TB
ExternalServices[External Services]
end
%% === PRIMARY FLOWS ===
%% Gateway to Core
REST --> Auth
MCP --> CapMgr
WebSocket --> Approval
%% Capability Token Lifecycle Flows
Auth --> CapMgr
CapMgr --> PermEngine
PermEngine --> Trust
PermEngine --> Approval
CapMgr --> Executor
Executor --> Assets
Executor --> ExternalServices
%% Core Service Interactions
Auth --> Redis
Identity --> Postgres
Identity --> Blockchain
Assets --> Postgres
Assets --> Queue
Trust --> Postgres
Trust --> Blockchain
Approval --> Redis
Approval --> WebSocket
CapMgr --> Postgres
CapMgr --> Redis
PermEngine --> Postgres
Executor --> Postgres
%% Queue Internal Connections
RabbitMQ --> Celery
RabbitMQ --> CeleryBeat
Celery --> ExternalServices
CeleryBeat --> Trust
%% Data Layer Interactions
Postgres <--> Redis
Redis --> WebSocket
Blockchain --> Trust
Files --> Assets
%% Asset Manager to External Services
Assets --> ExternalServices
%% Background Task Flows
Celery --> ExternalServices
Celery --> Postgres
%% Trust Engine Flows
Trust --> ExternalServices
Trust --> Blockchain
%% === STYLING ===
classDef gatewayStyle fill:#111316,stroke:#19727a,stroke-width:2px
classDef coreStyle fill:#0f1720,stroke:#274251,stroke-width:2px
classDef queueStyle fill:#111316,stroke:#2b3940,stroke-width:2px
classDef dataStyle fill:#101316,stroke:#2f2b20,stroke-width:2px
classDef externalStyle fill:#16171a,stroke:#3a2630,stroke-width:2px
class Gateway,REST,MCP,WebSocket gatewayStyle
class Core,Auth,Identity,Assets,Trust,Approval coreStyle
class Queue,RabbitMQ,Celery,CeleryBeat queueStyle
class Data,Postgres,Redis,Blockchain,Files dataStyle
class ExternalServices externalStyle
CirtusAI’s frontend provides three distinct interfaces for different user types: everyday users who want to control their AI, developers who integrate AI applications, and administrators who manage the platform.
This diagram shows the complete technical architecture of CirtusAI, illustrating how users, their personal assets, AI agents, the platform infrastructure, external services, and developer tools all interconnect to create a seamless AI identity and access management system.
Key architectural flows:
Trust & Verification: Trust Engine generates VAP certificates that external platforms use to verify AI identity and reputation
Developer Experience: Both SDK integration and MCP protocol support
User Control: All major AI decisions flow through the Approval System with real-time notifications to user devices
flowchart TD
%% === USER LAYER (TOP) ===
subgraph UserLayer [USER LAYER - Human Control]
direction TB
User[User<br/>Human Controller<br/>Ultimate Authority]
UserAssets[Personal Assets<br/>Email - Wallet<br/>Existing Accounts]
UserControls[User Controls<br/>Mobile App<br/>Web Dashboard]
User --> UserControls
User -.-> UserAssets
end
%% === PLATFORM CORE LAYER (CENTER) ===
subgraph Platform [CIRTUSAI PLATFORM - Core Infrastructure]
direction TB
%% Frontend Layer
subgraph Frontend [Frontend Services]
WebApp[Web Dashboard<br/>User Management<br/>Real-time Interface]
MobileApp[Mobile App<br/>Instant Approvals<br/>Push Notifications]
Gateway[API Gateway<br/>Request Routing<br/>Load Balancing]
end
%% Backend Layer
subgraph Backend [Backend Services]
Auth[Authentication<br/>JWT + API Keys<br/>Session Security]
Identity[Identity Manager<br/>DID Registry<br/>AI Registration]
Assets[Asset Manager<br/>Email/Wallet Control<br/>Resource Operations]
Trust[Trust Engine<br/>VAP Certificates<br/>Reputation Scoring]
Approval[Approval System<br/>User Consent<br/>Workflow Engine]
Access[Access Control<br/>Permission Gates<br/>Security Policies]
end
%% Data Layer
subgraph DataLayer [Data Infrastructure]
DB[PostgreSQL<br/>Main Database<br/>ACID Transactions]
Cache[Redis<br/>Cache + Sessions<br/>Real-time Data]
Chain[Blockchain<br/>DID Registry<br/>Immutable Records]
Files[File Storage<br/>Media + Logs<br/>S3/MinIO]
end
%% AI Infrastructure
subgraph ModelServices [Model Services]
AIIdentity[AI Digital Identity<br/>DID: did:ethr:0x...<br/>Unique Registration]
AIAssets[AI Assets<br/>Dedicated Email<br/>AI Wallet]
Reputation[Reputation System<br/>Trust Scoring<br/>Behavior Tracking]
end
end
%% === DEVELOPER INTEGRATION LAYER ===
subgraph DevLayer [DEVELOPER INTEGRATION - SDK & APIs]
direction TB
PythonSDK[Python SDK<br/>Type Safety<br/>Async Support]
JSSDK[JavaScript SDK<br/>React/Node.js<br/>Browser Support]
RestAPI[REST API<br/>OpenAPI Spec<br/>Direct HTTP Access]
MCP[MCP Protocol<br/>Universal Support<br/>Zero Modification]
end
%% === AI APPLICATIONS LAYER ===
subgraph AILayer [AI APPLICATIONS - Agents & Tools]
direction TB
CustomAgents[Custom AI Agents<br/>Trading Bots<br/>Email Assistants<br/>Booking Agents]
ExistingTools[Existing AI Tools<br/>Claude Desktop<br/>ChatGPT<br/>GitHub Copilot]
end
Most the content in the appendix was generated by AI and did not go through rigorous checking. Treat the below content as “for reference only”.
The platform should implement a clear, well-documented REST surface. Below is a compact reference; use this to generate an OpenAPI spec.
Problem statement
Suggested architecture:
| task status: { id, state: queued | running | completed | failed, result?, error? } |
Security, privacy, and compliance guidance
Operational recommendations
Developer ergonomics and SDK size control
When to put a tool in the SDK
Trade-offs summary
User-defined permission boundaries (max spending limits, allowed recipients, time windows)
Organizational policies for enterprise accounts (department budgets, approval chains)
Capability-specific constraints (email sending limits, transaction amounts)
Compliance requirements (KYC levels, geographic restrictions)
Real-time fraud detection using machine learning models
Behavioral anomaly detection (unusual transaction patterns, geographic outliers)
Reputation scoring based on historical actions and outcomes
Context analysis (time of day, device fingerprinting, network analysis)
AI identity reputation scores (0-1000 scale)
User trust relationship strength
Platform partner reputation and SLA compliance
Historical approval patterns and user feedback
The following OpenAPI fragments define the key endpoints for capability token management. These specifications follow industry standards and provide comprehensive request/response schemas.
Request a capability token with specific constraints and usage limits.
paths:
/v1/capabilities/request:
post:
summary: Request capability token
description: Request a capability token for specific actions with constraints
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [ai_identity, capability_id, purpose]
properties:
ai_identity:
type: string
description: AI agent DID or identity reference
example: "did:ethr:0x123...abc"
capability_id:
type: string
description: Capability identifier with version
example: "send_email.v2"
purpose:
type: string
description: Human-readable purpose for audit trail
example: "Send weekly financial reports to stakeholders"
constraints:
type: object
description: Capability-specific constraints
properties:
allowed_recipients:
type: array
items:
type: string
example: ["[email protected]", "[email protected]"]
max_amount:
type: number
example: 1000.00
currency:
type: string
example: "USD"
usage_limit:
type: integer
minimum: 1
maximum: 1000
example: 10
expires_in:
type: integer
description: Token TTL in seconds
minimum: 60
maximum: 86400
example: 3600
idempotency_key:
type: string
description: Client-generated idempotency key
example: "req_12345_abc"
responses:
200:
description: Capability token issued successfully
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum: [issued, pending_approval]
example: "issued"
capability_token:
type: string
description: Signed JWT capability token
example: "eyJhbGciOiJFZDI1NTE5In0..."
token_id:
type: string
example: "cap_789xyz"
expires_at:
type: string
format: date-time
example: "2025-08-30T15:30:00Z"
usage_limit:
type: integer
example: 10
constraints:
type: object
description: Applied constraints
202:
description: Approval required
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum: [pending_approval]
approval_id:
type: string
example: "apr_456def"
approval_url:
type: string
example: "https://app.cirtusai.com/approve/apr_456def"
estimated_wait:
type: integer
description: Estimated approval time in seconds
example: 300
approval_context:
type: object
properties:
action_summary:
type: string
example: "Send email to 3 recipients"
estimated_cost:
type: string
example: "$0.03"
risk_level:
type: string
enum: [low, medium, high]
example: "low"
400:
description: Invalid request
403:
description: Policy violation or insufficient permissions
429:
description: Rate limit exceeded
Execute an action using a capability token.
paths:
/v1/actions/execute:
post:
summary: Execute action with capability token
description: Execute a specific action using a valid capability token
security:
- CapabilityToken: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [action, payload, idempotency_key]
properties:
action:
type: string
description: Specific action to execute
example: "send_email"
payload:
type: object
description: Action-specific payload
example:
to: "[email protected]"
subject: "Monthly Report"
body: "Please find the monthly report attached."
attachments: []
idempotency_key:
type: string
description: Prevents duplicate execution
example: "exec_12345_def"
execution_context:
type: object
description: Optional execution metadata
properties:
user_agent:
type: string
source_ip:
type: string
trace_id:
type: string
responses:
200:
description: Action executed successfully
content:
application/json:
schema:
type: object
properties:
action_id:
type: string
example: "act_789ghi"
status:
type: string
enum: [success, partial_success, failed]
example: "success"
result:
type: object
description: Action-specific result
example:
message_id: "msg_123abc"
delivered_at: "2025-08-30T15:35:00Z"
action_receipt:
type: object
properties:
receipt_id:
type: string
example: "rcpt_456jkl"
signature:
type: string
description: Platform signature for non-repudiation
example: "0x789def..."
timestamp:
type: string
format: date-time
provider_receipt:
type: object
description: Third-party provider confirmation
token_usage:
type: object
properties:
remaining_uses:
type: integer
example: 9
token_expires_at:
type: string
format: date-time
400:
description: Invalid action or payload
401:
description: Invalid or expired capability token
403:
description: Action not permitted by token constraints
409:
description: Idempotency key conflict
429:
description: Rate limit exceeded
Discover available capabilities and their metadata.
paths:
/v1/capabilities/catalog:
get:
summary: Get capability catalog
description: Retrieve available capabilities with metadata and constraints
parameters:
- name: category
in: query
schema:
type: string
enum: [communication, financial, storage, computation, external_api]
description: Filter by capability category
- name: risk_level
in: query
schema:
type: string
enum: [low, medium, high]
description: Filter by risk level
- name: auto_approve
in: query
schema:
type: boolean
description: Filter by auto-approval eligibility
responses:
200:
description: Capability catalog
content:
application/json:
schema:
type: object
properties:
capabilities:
type: array
items:
type: object
properties:
capability_id:
type: string
example: "send_email.v2"
name:
type: string
example: "Send Email"
description:
type: string
example: "Send emails using AI identity with delivery tracking"
category:
type: string
example: "communication"
risk_level:
type: string
example: "low"
auto_approve:
type: boolean
example: true
estimated_cost:
type: string
example: "$0.01 per email"
constraints_schema:
type: object
description: JSON Schema for capability constraints
example_payload:
type: object
description: Example action payload
required_scopes:
type: array
items:
type: string
example: ["email:send", "identity:use"]
metadata:
type: object
properties:
total_capabilities:
type: integer
user_permissions:
type: object
platform_limits:
type: object
components:
securitySchemes:
CapabilityToken:
type: http
scheme: bearer
bearerFormat: JWT
description: Capability token issued by /v1/capabilities/request
ApiKey:
type: apiKey
in: header
name: X-API-Key
description: Platform API key for authentication
schemas:
CapabilityToken:
type: object
description: JWT capability token structure
properties:
header:
type: object
properties:
alg:
type: string
example: "EdDSA"
typ:
type: string
example: "JWT"
kid:
type: string
example: "cap-key-2025"
payload:
type: object
properties:
iss:
type: string
example: "cirtusai-platform"
sub:
type: string
description: AI identity DID
example: "did:ethr:0x123...abc"
aud:
type: string
example: "cirtusai-actions"
jti:
type: string
description: Unique token identifier
example: "cap_789xyz"
iat:
type: integer
description: Issued at timestamp
exp:
type: integer
description: Expiration timestamp
caps:
type: array
description: Granted capabilities
items:
type: object
properties:
action:
type: string
constraints:
type: object
usage_limit:
type: integer
minimum: 1
approval_id:
type: string
description: Reference to approval if required
Capability lifecycle
Approvals
Action execution
Trust & VAP
Admin & revocation
Audit & evidence
Webhooks & notifications
Assets & uploads
Wallet & crypto
Sandbox & developer utilities
Introspection & diagnostics
Important notes for API design
End of Appendix
The CirtusAI MCP server implements standard MCP protocol with enhanced metadata for capability management:
{
"tools": [
{
"name": "book_flight",
"description": "Search and book flights using AI identity",
"inputSchema": {
"type": "object",
"properties": {
"departure": {"type": "string", "description": "Departure city"},
"destination": {"type": "string", "description": "Destination city"},
"date": {"type": "string", "format": "date"}
}
},
"cirtusai": {
"capability_id": "travel_booking.v1",
"risk_level": "medium",
"auto_approve": false,
"estimated_cost": "$500-2000",
"requires_approval": true,
"approval_context": "Flight booking with payment authorization"
}
},
{
"name": "send_email",
"description": "Send email using AI identity",
"inputSchema": {
"type": "object",
"properties": {
"to": {"type": "string"},
"subject": {"type": "string"},
"body": {"type": "string"}
}
},
"cirtusai": {
"capability_id": "send_email.v2",
"risk_level": "low",
"auto_approve": true,
"estimated_cost": "$0.01",
"requires_approval": false
}
}
]
}
{
"method": "tools/call",
"params": {
"name": "book_flight",
"arguments": {
"departure": "San Francisco",
"destination": "Tokyo",
"date": "2025-09-15"
}
}
}
MCP Server Internal Flow:
POST /v1/capabilities/requestPOST /v1/actions/execute{
"content": [
{
"type": "text",
"text": "Flight booked successfully! Your confirmation number is ABC123."
}
],
"isError": false,
"cirtusai": {
"action_id": "act_789xyz",
"capability_token_id": "cap_456def",
"approval_id": "apr_123abc",
"execution_time": "2025-08-30T14:30:00Z",
"audit_receipt": {
"signed": true,
"receipt_id": "rcpt_890ghi",
"signature": "0x1234...",
"provider_confirmation": "booking_ref_abc123"
}
}
}
The CirtusAI MCP server can be deployed in multiple configurations:
# Install CirtusAI MCP server
npm install -g @cirtusai/mcp-server
# Configure with API credentials
cirtus-mcp configure --api-key="sk_test_..." --sandbox-mode
# Add to Claude Desktop config
{
"mcpServers": {
"cirtusai": {
"command": "cirtus-mcp",
"args": ["serve"]
}
}
}
{
"api_key": "sk_prod_...",
"base_url": "https://api.cirtusai.com",
"cache_capabilities": true,
"cache_ttl": 300,
"approval_timeout": 600,
"enable_audit_logging": true,
"approval_notification": {
"webhook_url": "https://company.com/webhooks/approvals",
"mobile_push": true
}
}
CirtusAI will deliver defined traffic quality thresholds (bot/human signal scoring), commit to agreed throughput and latency SLAs for partner endpoints, provide verifiable provenance and attribution receipts for conversions, and support revenue-sharing or referral settlement APIs. Partners will receive signed attestation tokens (VAPs) for each action that include issuer, subject (agent identity), action scope, expiry, and signature metadata to support disputed events and settlement reconciliation.
Example: Signed Attestation (JSON payload)
{
"iss": "cirtusai-platform",
"sub": "agent:weather-forecaster-42",
"action": "purchase:create",
"target": "partner:acme-checkout",
"issued_at": "2025-08-29T12:00:00Z",
"expires_at": "2025-08-29T12:05:00Z",
"attribution": {
"campaign_id": "spring_promo_2025",
"referral_token": "rft_1XyZ...",
"revenue_share": 0.15
},
"signature": {
"alg": "ED25519",
"sig": "MEUCIQDx...",
"key_id": "vap-key-2025"
}
}
sequenceDiagram
participant User as User
participant AITool as AI Tool<br/>Claude, Cursor, etc
participant MCP as MCP Server<br/>CirtusAI
participant Backend as CirtusAI Backend
participant Trust as Trust Engine
participant Approval as Approval Service
participant Assets as AI Assets
participant Platform as External Platform
Note over User,Platform: MCP Protocol with Capability Tokens
User->>AITool: 1. "Book a flight to Tokyo"
AITool->>MCP: 2. MCP Request<br/>tools/list
MCP->>Backend: 3. Get Available Capabilities
Backend->>MCP: 4. Return Capability Catalog<br/>flight_search, book_flight
MCP->>AITool: 5. Transform to MCP Tools
AITool->>MCP: 6. MCP Call<br/>tools/call: flight_search
MCP->>Backend: 7. Request Capability Token<br/>search_flights.v1
Backend->>Trust: 8. Evaluate Policy & Reputation
Backend->>MCP: 9. Issue Capability Token (auto-approved)
MCP->>Assets: 10. Execute Search with Token
Assets->>Platform: 11. Search Flights<br/>With VAP Certificate
Platform->>Assets: 12. Return Results
Assets->>Backend: 13. Flight Options + ActionReceipt
Backend->>MCP: 14. Search Results with Audit
MCP->>AITool: 15. MCP Response (formatted)
AITool->>User: 16. Show Flight Options
User->>AITool: 17. "Book option 2"
AITool->>MCP: 18. MCP Call<br/>tools/call: book_flight
MCP->>Backend: 19. Request Capability Token<br/>book_flight.v1 (high-risk)
Backend->>Trust: 20. Policy Check - Approval Required
Backend->>Approval: 21. Create ApprovalRequest
Approval->>User: 22. Push Notification<br/>"Authorize $847 flight booking?"
User->>Approval: 23. Approve with Face ID
Approval->>Backend: 24. Signed ApprovalReceipt
Backend->>MCP: 25. Issue Capability Token
MCP->>Assets: 26. Execute Booking with Token
Assets->>Platform: 27. Complete Payment & Booking<br/>With VAP + Capability Token
Platform->>Assets: 28. Booking Confirmation + Receipt
Assets->>Backend: 29. ActionReceipt + Provider Response
Backend->>MCP: 30. Success with Full Audit Trail
MCP->>AITool: 31. MCP Response
AITool->>User: 32. "Flight booked! Confirmation: ABC123"
This appendix consolidates the Capability Delegation Model and a focused SDK design that keeps the developer-facing surface small while shifting critical, trust-sensitive work to the platform.
Public surface (minimal):
High-level convenience wrappers:
Developer UX (5-line quickstart example):
from cirtusai import Client
c = Client.bootstrap(api_key="...") # 1
ai = c.ai("assistant-1") # 2
cap = ai.request_capability("send_email", {"from":"ai@..."}) # 3
c.wait_for_approval(cap.approval_id) # 4 (optional helper)
receipt = ai.execute_with_capability(cap.token, "send_email", payload) # 5
Notes:
from cirtusai import Client
# Initialize with API key and optional configuration
client = Client(api_key="sk_test_...", base_url="https://api.cirtusai.com")
# Single-line capability execution with built-in approval handling
receipt = await client.perform(
capability="send_email",
params={
"to": "[email protected]",
"subject": "Invoice #12345",
"body": "Please find your invoice attached."
},
ai_identity="assistant-finance-bot"
)
print(f"Email sent: {receipt.action_id}")
from cirtusai import Client, CapabilityRequest
client = Client(api_key="sk_test_...")
# Discover available capabilities
capabilities = await client.discover_capabilities(category="communication")
# Request specific capability with constraints
cap_request = CapabilityRequest(
capability_id="send_email.v2",
constraints={
"allowed_recipients": ["[email protected]", "[email protected]"],
"max_attachments": 5,
"usage_limit": 10
},
purpose="Send weekly financial reports",
expires_in=3600 # 1 hour
)
# Request capability (may require approval)
capability_token = await client.request_capability(cap_request)
# Handle approval if required
if capability_token.requires_approval:
approval = await client.wait_for_approval(
capability_token.approval_id,
timeout=300 # 5 minutes
)
capability_token = approval.capability_token
# Execute action with capability token
receipt = await client.execute_action(
capability_token=capability_token,
action="send_email",
payload={
"to": "[email protected]",
"subject": "Q3 Financial Report",
"body": "Please review the attached report."
}
)
# Request capability for multiple uses
capability_token = await client.request_capability(
CapabilityRequest(
capability_id="send_email.v2",
usage_limit=50,
expires_in=1800 # 30 minutes
)
)
# Execute multiple actions with the same token
recipients = ["[email protected]", "[email protected]", "[email protected]"]
receipts = []
for recipient in recipients:
receipt = await client.execute_action(
capability_token=capability_token,
action="send_email",
payload={
"to": recipient,
"subject": "Monthly Newsletter",
"body": "Here's your monthly update..."
}
)
receipts.append(receipt)
print(f"Sent {len(receipts)} emails successfully")
The SDK provides rich capability discovery to help developers understand what’s available and how to use it effectively:
# Get all available capabilities
all_caps = await client.discover_capabilities()
# Filter by category or risk level
communication_caps = await client.discover_capabilities(
category="communication",
risk_level="low"
)
# Get detailed capability metadata
email_cap = await client.get_capability_details("send_email.v2")
print(f"Description: {email_cap.description}")
print(f"Auto-approve: {email_cap.auto_approve}")
print(f"Required constraints: {email_cap.required_constraints}")
print(f"Example payload: {email_cap.example_payload}")
The SDK implements comprehensive error handling with automatic retries, circuit breakers, and graceful degradation:
from cirtusai import Client, CirtusError, ApprovalTimeoutError, TokenExpiredError
try:
receipt = await client.perform("send_email", params, retry_config={
"max_retries": 3,
"backoff_factor": 2.0,
"timeout": 30
})
except ApprovalTimeoutError as e:
# Handle approval timeout
print(f"Approval timed out: {e.approval_id}")
# Optionally poll for approval later
except TokenExpiredError as e:
# Token expired during execution
print("Token expired, requesting new capability")
# SDK can auto-retry with new token
except CirtusError as e:
# Generic platform error
print(f"Platform error: {e.code} - {e.message}")
if e.retriable:
# Implement exponential backoff retry
pass
from cirtusai import Client, SDKConfig
# Production configuration
config = SDKConfig(
base_url="https://api.cirtusai.com",
timeout=30,
max_retries=3,
cache_capabilities=True,
cache_ttl=300, # 5 minutes
enable_telemetry=True,
log_level="INFO"
)
client = Client(api_key="sk_prod_...", config=config)
# Development configuration with sandbox mode
dev_config = SDKConfig(
base_url="https://sandbox.cirtusai.com",
sandbox_mode=True,
mock_approvals=True, # Auto-approve for testing
log_level="DEBUG"
)
dev_client = Client(api_key="sk_test_...", config=dev_config)
Delegation flow (summary):
This section describes the end-to-end flow from user intent to capability issuance to successful task execution.
Send invoice email to [email protected] for $120. The SDK translates this into a structured capability request describing the intended action and constraints.Validation & security checks
sequenceDiagram
participant User as User
participant SDK as Developer SDK
participant Backend as CirtusAI Backend
participant Trust as Trust Engine
participant Approval as Approval Service
participant Connector as Platform Connector
participant External as External Service
User->>SDK: 1. Intent (send_email to alice)
SDK->>Backend: 2. POST /v1/capabilities/request {caps, purpose, idempotency_key}
Backend->>Trust: 3. Evaluate policy & reputation
alt approval required
Backend->>Approval: 4. Create ApprovalRequest
Approval->>User: 5. Notify (mobile/web)
User-->>Approval: 6. Approve
Approval->>Backend: 7. Signed ApprovalReceipt
end
Backend->>SDK: 8. {status: issued, cap_token}
SDK->>Backend: 9. POST /v1/actions/execute (Bearer cap_token, action, payload)
Backend->>Backend: 10. Verify cap_token signature, constraints, usage
Backend->>Connector: 11. Execute using platform-managed creds
Connector->>External: 12. External API call
External-->>Connector: 13. Provider response + receipt
Connector->>Backend: 14. Provider response
Backend->>SDK: 15. ActionReceipt + status
Caption: Sequence showing capability request, optional approval, token issuance, guarded execution via platform connectors, and signed action receipts for audit and settlement.
Decision: two-step capability issuance as default
We will adopt the two-step pattern (request → cap_token issuance → execute with token) as the default for capability-based side-effects. This provides the strongest security guarantees (least privilege, revocation, auditable approvals). To preserve a smooth developer and agent experience, official SDKs will expose a single high-level helper (for example, sdk.perform(...)) that discovers capability metadata, requests tokens when needed, waits or subscribes for approvals where required, and executes actions using issued tokens. Low-risk, auto-approved capabilities may be optimized later with a combined execute-with-issuance endpoint, but the canonical flow remains two-step for security and compliance.
SDK responsibilities (client):
Backend responsibilities (platform):
sequenceDiagram
participant SDK as Developer SDK
participant EA as External Agent
participant Backend as CirtusAI Backend
participant Trust as Trust Engine
participant Approval as Approval Service
participant User as End User
participant External as External Service
participant Audit as Audit Log
EA->>SDK: build capability request (name, constraints)
SDK->>Backend: POST /v1/capabilities/request {ai_did, caps, purpose, idempotency}
Backend->>Trust: policy & reputation check
alt requires user approval
Backend->>Approval: create ApprovalRequest(approval_id)
Approval->>User: notify (push / mobile / email)
User-->>Approval: approve/deny
Approval->>Backend: approval result
end
Backend->>Backend: issue cap_token (signed, constrained, jti)
Backend-->>SDK: {status: issued, cap_token} / {status: pending, approval_id}
SDK->>EA: deliver cap_token or pending status
EA->>Backend: POST /v1/actions/execute (Authorization: Bearer cap_token, action, payload)
Backend->>Backend: verify cap_token signature, exp, usage, constraints
Backend->>Trust: log attempt, update metrics
Backend->>External: perform action using platform-managed creds
External-->>Backend: provider response (success/fail, provider_receipt)
Backend->>Audit: write ActionReceipt (signed)
Backend->>Trust: update reputation / issue VAP if applicable
Backend-->>EA: ActionReceipt + provenance
Note over Backend,External: Revocation / CRL flow
Admin->>Backend: POST /v1/admin/revocations {jti, reason}
Backend->>Audit: record revocation
Backend->>Trust: publish CRL / webhook revocation
External->>Backend: optional introspect(token)