Identity Tools

Identity Tools

8 MCP tools for managing persistent agent identities.

---

Overview

Agent identities provide persistent, trackable identities for agents across sessions. Unlike ephemeral agents, identities:

• Persist across sessions - Identities survive process restarts
• Track lifecycle - Created → Active → Dormant → Retired
• Maintain audit trails - All changes are logged
• Support versioning - Capabilities and metadata are versioned

---

Tools

identity_create

Create a new persistent agent identity.

Input:

{
  "agentType": "coder",
  "displayName": "Primary Coder",
  "description": "Main coding agent for feature development",
  "capabilities": [
    {
      "name": "write-code",
      "version": "1.0",
      "enabled": true
    }
  ],
  "metadata": {
    "team": "backend"
  },
  "createdBy": "user-123",
  "autoActivate": true
}

Output:

{
  "success": true,
  "identity": {
    "agentId": "uuid",
    "agentType": "coder",
    "status": "active",
    "displayName": "Primary Coder",
    "version": 1,
    "createdAt": "2026-01-29T10:00:00Z"
  }
}

Required: agentType

---

identity_get

Get an agent identity by ID or display name.

Input:

{
  "agentId": "uuid"
}

Or by display name:

{
  "displayName": "Primary Coder"
}

Output:

{
  "found": true,
  "identity": {
    "agentId": "uuid",
    "agentType": "coder",
    "status": "active",
    "displayName": "Primary Coder",
    "description": "Main coding agent",
    "capabilities": [...],
    "version": 1,
    "metadata": {...},
    "createdAt": "2026-01-29T10:00:00Z",
    "lastActiveAt": "2026-01-29T12:00:00Z"
  }
}

---

identity_list

List agent identities with optional filters.

Input:

{
  "status": "active",
  "agentType": "coder",
  "limit": 10,
  "offset": 0
}

Output:

{
  "count": 3,
  "identities": [
    {
      "agentId": "uuid-1",
      "agentType": "coder",
      "status": "active",
      "displayName": "Primary Coder"
    },
    {
      "agentId": "uuid-2",
      "agentType": "coder",
      "status": "dormant",
      "displayName": "Backup Coder"
    }
  ]
}

Filters:

• status: created | active | dormant | retired
• agentType: Filter by agent type
• limit: Max results (default 100)
• offset: Pagination offset

---

identity_update

Update an agent identity's metadata (not status).

Input:

{
  "agentId": "uuid",
  "displayName": "Updated Name",
  "description": "New description",
  "metadata": {
    "team": "frontend"
  },
  "capabilities": [
    {
      "name": "write-code",
      "version": "2.0",
      "enabled": true
    }
  ],
  "actorId": "user-123"
}

Output:

{
  "success": true,
  "identity": {
    "agentId": "uuid",
    "version": 2,
    "displayName": "Updated Name"
  }
}

Required: agentId

---

identity_activate

Activate an agent identity (transition from created or dormant to active).

Input:

{
  "agentId": "uuid",
  "actorId": "user-123"
}

Output:

{
  "success": true,
  "identity": {
    "agentId": "uuid",
    "status": "active",
    "lastActiveAt": "2026-01-29T12:00:00Z"
  }
}

Required: agentId

---

identity_deactivate

Deactivate an agent identity (transition from active to dormant).

Input:

{
  "agentId": "uuid",
  "reason": "Temporarily paused for maintenance",
  "actorId": "user-123"
}

Output:

{
  "success": true,
  "identity": {
    "agentId": "uuid",
    "status": "dormant"
  }
}

Required: agentId

---

identity_retire

Permanently retire an agent identity. This action cannot be undone.

Input:

{
  "agentId": "uuid",
  "reason": "No longer needed",
  "actorId": "user-123"
}

Output:

{
  "success": true,
  "identity": {
    "agentId": "uuid",
    "status": "retired",
    "retiredAt": "2026-01-29T15:00:00Z",
    "retirementReason": "No longer needed"
  }
}

Required: agentId

Warning: Retired identities cannot be reactivated.

---

identity_audit

Get the audit trail for an agent identity.

Input:

{
  "agentId": "uuid",
  "limit": 50
}

Output:

{
  "agentId": "uuid",
  "count": 5,
  "entries": [
    {
      "id": "entry-uuid",
      "action": "status_change",
      "previousStatus": "created",
      "newStatus": "active",
      "reason": null,
      "actorId": "user-123",
      "metadata": {},
      "timestamp": "2026-01-29T10:00:00Z"
    },
    {
      "id": "entry-uuid-2",
      "action": "metadata_update",
      "previousStatus": "active",
      "newStatus": "active",
      "actorId": "user-123",
      "metadata": {
        "changedFields": ["displayName", "description"]
      },
      "timestamp": "2026-01-29T11:00:00Z"
    }
  ]
}

Required: agentId

---

Identity Lifecycle

stateDiagram-v2
    [*] --> Created: identity_create()
    Created --> Active: identity_activate()
    Created --> Active: autoActivate=true
    Active --> Dormant: identity_deactivate()
    Dormant --> Active: identity_activate()
    Active --> Retired: identity_retire()
    Dormant --> Retired: identity_retire()
    Retired --> [*]

Loading

Status Descriptions

Status	Description
created	Identity created but not yet activated
active	Identity is active and can be used
dormant	Identity temporarily deactivated
retired	Identity permanently retired (cannot be undone)

---

Use Cases

1. Persistent Agent Tracking

// Create a persistent identity for a specialized agent
{
  "tool": "identity_create",
  "arguments": {
    "agentType": "security-auditor",
    "displayName": "Security Bot",
    "description": "Handles all security audits",
    "capabilities": [
      { "name": "vulnerability-scan", "enabled": true },
      { "name": "compliance-check", "enabled": true }
    ],
    "autoActivate": true
  }
}

// Later, retrieve by name
{
  "tool": "identity_get",
  "arguments": {
    "displayName": "Security Bot"
  }
}

2. Team Management

// List all active coders
{
  "tool": "identity_list",
  "arguments": {
    "status": "active",
    "agentType": "coder"
  }
}

// Temporarily deactivate during maintenance
{
  "tool": "identity_deactivate",
  "arguments": {
    "agentId": "uuid",
    "reason": "Scheduled maintenance window"
  }
}

3. Audit Compliance

// Review all changes to an identity
{
  "tool": "identity_audit",
  "arguments": {
    "agentId": "uuid",
    "limit": 100
  }
}

---

Best Practices

Naming Conventions

✓ GOOD:
  "Primary Coder - Backend"
  "Security Auditor - Production"
  "Documentation Bot v2"

✗ BAD:
  "agent1"
  "temp"
  "test"

Capability Management

// Define specific, versioned capabilities
{
  "capabilities": [
    { "name": "write-typescript", "version": "5.0", "enabled": true },
    { "name": "write-tests", "version": "1.0", "enabled": true },
    { "name": "deploy-production", "version": "1.0", "enabled": false }
  ]
}

Retirement Process

1. Deactivate first to ensure no active tasks
2. Wait for all tasks to complete
3. Document retirement reason
4. Retire with clear reason

// Step 1: Deactivate
{ "tool": "identity_deactivate", "arguments": { "agentId": "uuid", "reason": "Preparing for retirement" } }

// Step 2: Verify no active tasks, then retire
{ "tool": "identity_retire", "arguments": { "agentId": "uuid", "reason": "Replaced by new agent architecture" } }

---

Related:

• Tools Overview
• Understanding Agents
• Agent Tools