Architecture Overview

ArmorIQ uses a proxy-based architecture where all agent requests flow through a secure verification layer before reaching MCP servers.

System Components

Request Flow

1. Plan Capture

captured_plan = client.capture_plan(
    llm="gpt-4",
    prompt="Fetch sales data and analyze"
)

Flow:

• SDK sends plan to ArmorIQ API
• API validates plan structure against registry
• Canonical representation created
• Plan stored with unique ID
• Plan details returned to agent

2. Token Generation

token = client.get_intent_token(
    plan_capture=captured_plan,
    policy={"allow": ["*"], "deny": []}
)

Flow:

• SDK sends plan + policy to ArmorIQ API
• API verifies plan structure
• Canonical plan hash generated
• Token cryptographically signed with:
  • Plan hash
  • Policy constraints
  • Expiration time
  • User/agent identity
• Signed token returned to agent

3. Action Execution

result = client.invoke(
    mcp="data-mcp",
    action="fetch_data",
    intent_token=token,
    params={"query": "sales"}
)

Flow:

• SDK sends request to ArmorIQ Proxy with token and Merkle proof
• Proxy verifies:
  • Ed25519 signature validity
  • Merkle proof of action in plan
  • Policy constraints
  • Token expiration
  • Rate limits
• If verified, request forwarded to MCP
• MCP response returned to agent with signature
• Audit log created

Security Layers

Layer 1: Authentication

• API key validation
• User identity verification
• Agent identification

Layer 2: Authorization (Policy)

• Action allowlist/denylist
• Time-based restrictions
• IP whitelisting
• Rate limiting

Layer 3: Intent Verification

• Token signature validation
• Plan hash verification
• Merkle proof validation
• Action-plan matching
• Token expiration check

Layer 4: Audit Trail

• Complete request logging
• Plan history tracking
• Token usage monitoring
• Anomaly detection

Component Details

ArmorIQ API

Responsibilities:

• Token generation and signing
• Plan canonicalization
• Plan validation
• Cryptographic operations

ArmorIQ Proxy

Responsibilities:

• Request gateway and routing
• Token signature verification
• Merkle proof verification
• Policy enforcement
• Rate limiting
• Audit logging

MCP Servers

Responsibilities:

• Execute specific business logic
• Return structured results
• Follow MCP protocol standards

MCP Registry

Responsibilities:

• Service discovery
• Action catalog
• Schema validation
• Version management

Complete Agent Flow

Here's how a complete agent interaction works from user input to result:

Flow Explanation

Planning Phase:

1. User sends message to agent backend
2. Backend streams request to LLM provider
3. LLM determines required tool calls (e.g., "loan_calculator")
4. Backend calls capture_plan() with tool calls
5. SDK sends plan to ArmorIQ API for token generation
6. API validates plan and returns signed IntentToken
7. Backend receives token for execution

Execution Phase:

1. Backend calls invoke() with action and token
2. SDK sends request to Proxy with token and Merkle proof
3. Proxy performs three-step verification:
   • Verifies Ed25519 signature
   • Validates Merkle proof (action in plan)
   • Enforces policy constraints
4. Proxy forwards request to appropriate MCP server
5. MCP executes action and returns result
6. Proxy signs result and returns to SDK
7. SDK returns result to backend
8. Backend streams result to user

Deployment Architecture

Cloud Deployment

Load Balancer
   │
   ├──▶ API Instance (Token Generation)
   │
   ├──▶ Proxy Instances (Request Verification)
   │     └── Connects to MCP Servers
   │
   └──▶ Database (Plans, Tokens, Audit Logs)

Scalability

ArmorIQ is designed for horizontal scaling:

• Stateless Services: Add more instances as needed
• Token Caching: Reduce token generation load
• Distributed Verification: Multiple proxy instances
• Load Balancing: Distribute requests evenly

Next Steps

• Intent Plans - Learn about plan structure
• Security Model - Deep dive into security
• Token Lifecycle - How tokens work