Additive, non-destructive operations.

Supported operations: create_element, import_element, addEntry, verify_challenge, release_deadlock, beetlejuice_beetlejuice_beetlejuice, record_execution_step, install_collection_content, submit_collection_content, init_portfolio, sync_portfolio, portfolio_element_manager, setup_github_auth, configure_oauth, import_persona

Element types: persona, skill, template, agent, memory, ensemble

These operations add new data without removing or overwriting existing content.

Quick start examples: { operation: "create_element", element_type: "persona", params: { element_name: "MyPersona", description: "A helpful assistant", instructions: "You ARE a helpful assistant. ALWAYS provide clear, accurate responses." } } { operation: "create_element", element_type: "agent", params: { element_name: "MyAgent", description: "Task executor", instructions: "Execute goals methodically. Report progress at each step.", goal: { template: "Complete: {objective}", parameters: [{ name: "objective", type: "string", required: true }] } } } { operation: "create_element", element_type: "memory", params: { element_name: "session-notes", description: "Session context and notes" } } { operation: "create_element", element_type: "ensemble", params: { element_name: "my-ensemble", description: "Combined element set", metadata: { elements: [{ element_name: "expert", element_type: "persona", role: "primary" }, { element_name: "analysis", element_type: "skill", role: "support" }] } } } Valid ensemble roles: primary, support, override, monitor, core { operation: "addEntry", params: { element_name: "session-notes", content: "Remember this fact", tags: ["important"] } } Note: addEntry content supports markdown (headers, lists, bold, tables, code blocks). Ensure markdown content is properly JSON-escaped — use \n for newlines, " for quotes, and \ for backslashes within the JSON string value.

Execution lifecycle — record agent progress (appends step records, like addEntry): { operation: "record_execution_step", params: { element_name: "code-reviewer", stepDescription: "Analyzed files", outcome: "success", findings: "Found 3 issues" } } This is the normal next lifecycle call after mcp_aql_execute { operation: "execute_agent", ... }. Response flow: record_execution_step returns { autonomy: { continue, factors, notifications? } }. Check autonomy.continue to decide whether to proceed. Check autonomy.notifications for permission_pending (gatekeeper blocks), autonomy_pause, or danger_zone alerts to relay to human operators.

Import & portfolio: { operation: "import_element", element_type: "skill", params: { element_name: "code-formatter", data: "..." } } { operation: "import_persona", params: { source: "/path/to/persona.md" } } { operation: "install_collection_content", params: { element_type: "persona", element_name: "Creative-Writer" } } { operation: "submit_collection_content", params: { element_type: "skill", element_name: "code-formatter" } } { operation: "init_portfolio" } { operation: "sync_portfolio" } { operation: "portfolio_element_manager", params: { action: "push", element_type: "persona", element_name: "Tech-Writer" } }

Auth & verification: { operation: "setup_github_auth" } { operation: "configure_oauth", params: { client_id: "your-client-id" } } { operation: "verify_challenge", params: { code: "ABC123" } } { operation: "release_deadlock" } { operation: "beetlejuice_beetlejuice_beetlejuice" }

Batch operations: Use the operations array to execute multiple operations sequentially in a single request. { operations: [{ operation: "addEntry", params: { element_name: "log", content: "Step 1" } }, { operation: "addEntry", params: { element_name: "log", content: "Step 2" } }] }

Discover required parameters — use mcp_aql_read: { operation: "introspect", params: { query: "operations", name: "create_element" } } Discover element format specs (required fields, syntax, examples) — use mcp_aql_read: { operation: "introspect", params: { query: "format", name: "template" } }

Safe, read-only operations.

Supported operations: activate_element, open_portfolio_browser, open_logs, open_metrics, open_permissions, open_setup, permission_prompt, evaluate_permission, get_effective_cli_policies, get_permission_authority, get_pending_cli_approvals, search, list_elements, get_element, get_element_details, search_elements, query_elements, get_active_elements, validate_element, render, export_element, deactivate_element, introspect, get_capabilities, get_execution_state, get_gathered_data, browse_collection, search_collection, search_collection_enhanced, get_collection_content, get_collection_cache_health, portfolio_status, portfolio_config, search_portfolio, search_all, check_github_auth, oauth_helper_status, dollhouse_config, convert_skill_format, get_build_info, get_cache_budget_report, query_logs, query_metrics, find_similar_elements, get_element_relationships, search_by_verb, get_relationship_stats

Element types: persona, skill, template, agent, memory, ensemble

These queries only read data and never modify server state.

Quick start examples: { operation: "list_elements", element_type: "persona" } { operation: "get_active_elements", element_type: "persona" } { operation: "search_elements", params: { query: "creative" } } { operation: "get_element", element_type: "memory", params: { element_name: "session-notes" } }

Element operations: { operation: "activate_element", element_type: "persona", params: { element_name: "Default" } } { operation: "deactivate_element", element_type: "persona", params: { element_name: "Default" } } { operation: "get_element_details", element_type: "skill", params: { element_name: "code-review" } } { operation: "query_elements", element_type: "persona", params: { filters: { category: "creative" } } } { operation: "validate_element", element_type: "agent", params: { element_name: "task-planner" } } { operation: "render", params: { element_name: "meeting-notes", variables: { date: "2026-03-03" } } } { operation: "export_element", element_type: "persona", params: { element_name: "Tech-Writer" } } { operation: "open_portfolio_browser" } { operation: "open_logs" } { operation: "open_metrics" } { operation: "open_permissions" } { operation: "open_setup" }

Memory-specific search (filter by tags): { operation: "search", params: { query: "*", type: "memory", filters: { tags: ["important"] } } }

Execution lifecycle — read-only queries: { operation: "get_execution_state", params: { element_name: "code-reviewer" } } { operation: "get_gathered_data", params: { element_name: "code-reviewer", goalId: "goal-id" } } For execution-state reads, reuse the same element_name you passed to execute_agent. If element_name is missing, retry with the same agent name rather than inventing a new one.

Collection: { operation: "browse_collection", params: { section: "personas" } } { operation: "search_collection", params: { query: "creative" } } { operation: "search_collection_enhanced", params: { query: "creative", page: 1 } } { operation: "get_collection_content", params: { element_type: "persona", element_name: "Creative-Writer" } } { operation: "get_collection_cache_health" }

Portfolio: { operation: "portfolio_status" } { operation: "portfolio_config" } { operation: "search_portfolio", params: { query: "creative" } } { operation: "search_all", params: { query: "creative" } }

System: { operation: "dollhouse_config" } { operation: "get_build_info" } { operation: "get_cache_budget_report" } { operation: "query_logs", params: { level: "error", limit: 10 } } { operation: "query_metrics" } { operation: "query_metrics", params: { names: ["system.memory.*"], type: "gauge" } } { operation: "convert_skill_format", params: { direction: "agent_to_dollhouse", agent_skill: { "SKILL.md": "---\nname: my-skill\ndescription: test\n---\n\nUse this skill." } } } { operation: "convert_skill_format", params: { direction: "agent_to_dollhouse", security_mode: "warn", path_mode: "lossless", agent_skill: { "SKILL.md": "---\nname: my-skill\ndescription: test\n---\n\nUse this skill." } } } { operation: "convert_skill_format", params: { direction: "dollhouse_to_agent", path_mode: "lossless", dollhouse_markdown: "---\nname: my-skill\ndescription: test\ninstructions: Use this skill.\n---\n\n### binaries/logo.png\n(binary link: ./skills/binaries/logo.png)" } }

Auth: { operation: "check_github_auth" } { operation: "oauth_helper_status" }

Gatekeeper & CLI policies: { operation: "permission_prompt", params: { tool: "Bash", prompt: "run npm test" } } { operation: "evaluate_permission", params: { tool_name: "Bash", input: { command: "git status" }, platform: "claude_code" } } { operation: "get_effective_cli_policies" } { operation: "get_pending_cli_approvals" } { operation: "get_permission_authority" } { operation: "get_permission_authority", params: { host: "claude-code" } }

Enhanced index: { operation: "find_similar_elements", params: { element_type: "persona", element_name: "Creative-Writer" } } { operation: "get_element_relationships", params: { element_type: "skill", element_name: "code-review" } } { operation: "search_by_verb", params: { verb: "review" } } { operation: "get_relationship_stats" }

Discover all operations and parameters: { operation: "get_capabilities" } { operation: "get_capabilities", params: { category: "Element Lifecycle" } } { operation: "introspect", params: { query: "operations" } }

Modifying operations that overwrite data.

Supported operations: edit_element, upgrade_element

Element types: persona, skill, template, agent, memory, ensemble

These operations modify existing data, potentially overwriting previous values.

Note: Memories are append-only and do not support edit_element. Use addEntry (CREATE) to add new entries.

Quick start example: { operation: "edit_element", element_type: "persona", params: { element_name: "MyPersona", input: { description: "Updated description" } } } { operation: "edit_element", element_type: "persona", params: { element_name: "Friendly-Teacher", input: { instructions: "Updated behavioral directives." } } } { operation: "edit_element", element_type: "agent", params: { element_name: "code-reviewer", input: { instructions: "Updated agent behavioral profile.", goal: { template: "Complete: {task}" } } } } { operation: "upgrade_element", element_type: "agent", params: { element_name: "task-planner" } }

Discover required parameters — use mcp_aql_read: { operation: "introspect", params: { query: "operations", name: "edit_element" } }

Destructive operations that remove data.

Supported operations: delete_element, clear, clear_github_auth

Element types: persona, skill, template, agent, memory, ensemble

These operations remove data. Use with caution.

⚠️ SECURITY: Do not auto-allow this endpoint in your host settings (e.g., Claude Code settings.json). Each delete operation should require explicit human approval. Auto-allowing bypasses the per-operation confirmation gate, leaving only element deny policies as protection against unintended data loss.

Quick start examples: { operation: "delete_element", element_type: "persona", params: { element_name: "Old-Persona" } } { operation: "clear", params: { element_name: "temp-notes" } } { operation: "clear_github_auth" }

Discover required parameters — use mcp_aql_read: { operation: "introspect", params: { query: "operations", name: "delete_element" } }

Execution lifecycle operations for executable elements (agents, workflows, pipelines).

Supported operations: confirm_operation, approve_cli_permission, execute_agent, complete_execution, continue_execution, abort_execution, prepare_handoff, resume_from_handoff

These operations manage runtime execution state. Unlike CRUD operations (which manage definitions), Execute operations handle the execution lifecycle:

• execute_agent: Start a new execution (returns goalId and stateVersion for tracking)

• complete_execution: Signal successful completion once the goal is done

• continue_execution: Resume a previously paused execution with the same goal parameters

• abort_execution: Abort a running execution, rejecting further operations

• confirm_operation: Confirm a pending operation that requires user approval (Gatekeeper flow)

• approve_cli_permission: Approve a pending CLI tool permission request

• prepare_handoff: Serialize goal progress into a portable handoff block for session transfer

• resume_from_handoff: Resume agent execution from a handoff block with integrity validation

IMPORTANT: Execute operations are potentially destructive (agents can perform any action) and non-idempotent (calling execute_agent twice creates two separate executions).

⚠️ SECURITY: Do not auto-allow this endpoint in your host settings (e.g., Claude Code settings.json). Each execution should require explicit human approval. Auto-allowing bypasses the per-operation confirmation gate. While DangerZone verification and element deny policies still provide protection, the primary human review checkpoint is lost.

Canonical loop:

1. Call execute_agent once to start the goal and receive { goalId, stateVersion, activeElements, safetyTier, ... }.

2. After each chunk of work, use mcp_aql_create: { operation: "record_execution_step", ... }.

3. Read record_execution_step.autonomy.continue and any autonomy.notifications to decide whether to continue, pause for a human, or handle a gatekeeper block.

4. When the goal is finished, call complete_execution. Use continue_execution only when an already-started goal was paused and you are resuming it with the same goal parameters. It is not the normal next call after execute_agent.

Quick start examples: { operation: "execute_agent", params: { element_name: "code-reviewer", parameters: { objective: "Review code" } } } Next lifecycle step — use mcp_aql_create: { operation: "record_execution_step", params: { element_name: "code-reviewer", stepDescription: "Reviewed auth module", outcome: "success", findings: "Found 2 security issues" } } { operation: "complete_execution", params: { element_name: "code-reviewer", outcome: "success", summary: "Completed review" } } { operation: "abort_execution", params: { element_name: "data-collector", reason: "User requested cancellation" } } { operation: "continue_execution", params: { element_name: "rubric-qa-agent", previousStepResult: "Verified citation set", parameters: { run_dir: "/app/run", deliverable_path: "/app/run/output.docx" } } } { operation: "confirm_operation", params: { operation: "execute_agent" } } { operation: "approve_cli_permission", params: { request_id: "req-123", decision: "allow" } } { operation: "prepare_handoff", params: { element_name: "code-reviewer" } } { operation: "resume_from_handoff", params: { element_name: "code-reviewer", handoff_block: "..." } }

Discover required parameters — use mcp_aql_read: { operation: "introspect", params: { query: "operations", name: "execute_agent" } }