NV oOS AI Assistant Administration
Accuracy note (2026-09-15): this skill was rewritten after a live
verification pass against plugin v1.1.79 (includes/assistants/,
includes/cli/, includes/rest/) and the Design Stack deployment. Every
meta key, command, and route below is code-verified. The previous version
of this skill documented _assistant_* / _peer_* meta keys that the
plugin has never stored — do not use them.
When to use this skill
Trigger when ANY of the following is true:
- Creating, editing, or deleting AI assistant configurations.
- Changing an assistant's model provider (OpenAI, Gemini, Anthropic, Ollama, etc.).
- Configuring an assistant's system prompt, temperature, or tool access.
- Setting up or removing peer-to-peer federation records between WordPress sites.
- Listing all assistants with their current model, provider, and status.
- Querying which tools are enabled for a specific assistant.
- Debugging assistant behavior — checking configuration, tool access, or peer routing.
- Checking whether a specific NV oOS assistant / MCP server ("kate agent", "ECA agent", …) is enabled in the current editor session.
- Answering "is agent X available?" / "what tools does this MCP expose?" from inside a coding-agent session.
- Managing assistant-specific vector store or memory settings.
- Cloning an assistant configuration for testing or staging environments.
Mental model
Two CPT-backed entity types, plus a small set of verified interfaces:
AI ASSISTANT (CPT: mcp_ai_assistant) AI PEER (CPT: ai_peer)
├── title / post_status ├── title
├── _wp_mcp_ai_provider ├── _wp_mcp_ai_peer_mcp_url
├── _wp_mcp_ai_model ├── _wp_mcp_ai_peer_capabilities
├── _wp_mcp_ai_system_prompt ├── _wp_mcp_ai_peer_health_status
├── _wp_mcp_ai_tools (serialized slug array) ├── _wp_mcp_ai_peer_last_verified
├── _wp_mcp_ai_credentials (hashed tokens) ├── _wp_mcp_ai_peer_site_url
└── mcp_ai_required_capability └── … (see peer meta table)
INTERFACES (in order of reliability):
1. WP-CLI wp mcp-ai assistant|credential|tool|provider|chat|health|log …
2. REST https://<site>/wp-json/mcp-ai/v1/chat + /mcp (JSON-RPC) + /tools
3. Admin UI assistant CPT editor + federation pages
4. toolkit_cpt MCP tool — Pro-only, not guaranteed to be exposed
Relationships:
- An AI Assistant (
mcp_ai_assistant) is one row per assistant persona.
Model, provider, prompt, temperature, and the assigned tool-slug array all
live in _wp_mcp_ai_* post meta (plus mcp_ai_required_capability).
- An AI Peer (
ai_peer) is a federation-directory record pointing at a
remote MCP server: MCP/OpenAPI URLs, JWKS URI, capabilities, quotas, and a
health status that is refreshed by verification runs. Peers only render in
the admin federation page when enable_federation_directory is on.
toolkit_cpt (WP_MCP_AI_Pro_Tool_CPT,
addons/pro/includes/tools/infrastructure/class-wp-mcp-ai-pro-tool-cpt.php)
is the generic CPT CRUD MCP tool (group wordpress-core, pro capability
flag). It is NOT the single interface: it may be absent from a given
deployment's tools/list. Always verify it exists before scripting against
it; WP-CLI and the REST routes are the always-available paths.
WP-CLI command surface (verified against includes/cli/)
| Command |
Purpose |
wp mcp-ai assistant list [--status=any|publish|draft|trash] [--format] |
List assistants (title, status, legacy model column — see quirk below) |
wp mcp-ai assistant get <id> [--format=json] |
Post-level details; only shows mcp_ai_*-prefixed meta (quirk below) |
wp mcp-ai assistant create --title=<t> [--status=publish] [--model] [--system-prompt] [--porcelain] |
Create assistant; --porcelain prints the new ID |
wp mcp-ai assistant update <id> [--title] [--status] [--model] [--system-prompt] |
Update assistant |
wp mcp-ai assistant delete <id> [--force] [--yes] |
Trash or permanently delete |
wp mcp-ai assistant export <id> [--file=<name.json>] |
Export config JSON (stdout or uploads/mcp-ai/exports/) |
wp mcp-ai assistant import [--file=<name.json> | --stdin] [--porcelain] |
Import from exports dir or stdin |
wp mcp-ai credential list [<assistant-id>] [--format] |
List issued credentials |
wp mcp-ai credential issue <assistant-id> [--user=<id>] [--porcelain] |
Issue token; --porcelain prints cred_xxxxx.SECRET once |
wp mcp-ai credential revoke <assistant-id> <credential-id> [--yes] |
Revoke a token |
wp mcp-ai tool list [--status=enabled|disabled] [--format=ids] |
Discover assignable tool slugs (registry + enabled state) |
wp mcp-ai tool enable <slug> / wp mcp-ai tool disable <slug> [--yes] |
Toggle global tool availability |
wp mcp-ai provider list / provider test <slug> / provider models <slug> |
Provider config status, connectivity test, model list |
wp mcp-ai chat "<message>" [--assistant=<id>] [--model] [--provider] [--stream] [--format=json] |
One-shot chat via the model router |
wp mcp-ai health / wp mcp-ai log / wp mcp-ai cache clear / wp mcp-ai version |
Diagnostics |
wp mcp-ai toolkit list | enable <key> | disable <key> (Pro) |
Pro toolkit settings keys (enable_crm_toolkit, …) — not assistant CRUD |
There is no wp mcp-ai peer command — peer records are edited via post
meta or the admin UI. (Older versions of this skill claimed peer list /
peer test; those commands do not exist in v1.1.79.)
CLI quirks you will hit (code-verified)
assistant create|update --model=… and --system-prompt=… write legacy
mcp_ai_model / mcp_ai_system_prompt meta keys. The chat runtime reads
_wp_mcp_ai_model / _wp_mcp_ai_system_prompt, so those flags currently
have no runtime effect — set the _wp_mcp_ai_* keys explicitly.
assistant list reads mcp_ai_model (usually empty) and assistant get
only collects meta keys starting with mcp_ai_, which misses every
_wp_mcp_ai_* key. Inspect real config with wp post meta get instead.
wp mcp-ai provider list and wp mcp-ai chat fatal on builds before the
CLI fix in #6625 (see Known Issues).
Verified meta keys
mcp_ai_assistant
Constants in includes/assistants/class-wp-mcp-ai-assistant-cpt.php:
| Key |
Type |
Purpose |
_wp_mcp_ai_provider |
string |
Provider slug (openai, gemini, anthropic, deepseek, ollama, …) |
_wp_mcp_ai_model |
string |
Model identifier (gpt-4o-mini, gemini-2.5-flash, …) |
_wp_mcp_ai_temperature |
float |
Sampling temperature |
_wp_mcp_ai_system_prompt |
string |
Persona / system prompt |
_wp_mcp_ai_tools |
array (serialized) |
Assigned tool slugs — must be a real PHP array |
_wp_mcp_ai_credentials |
array |
Issued credentials (hashed). Never hand-edit |
_wp_mcp_ai_classification |
string |
Information label; defaults to internal |
mcp_ai_required_capability |
string |
Capability gate for tool calls — no _wp_ prefix (manage_options, edit_posts) |
_wp_mcp_ai_vector_store_id |
string |
OpenAI vector store for RAG |
_wp_mcp_ai_memory_files |
array |
Memory file attachment IDs |
_wp_mcp_ai_corpus_name |
string |
Corpus name for knowledge routing |
_wp_mcp_ai_tool_shortcuts |
array |
Tool shortcut definitions |
_wp_mcp_ai_harness_profile |
array (JSON) |
Agent-harness profile (memory summary etc.) |
ai_peer
Constants in includes/class-wp-mcp-ai-ai-peer-cpt.php:
| Key |
Type |
Purpose |
_wp_mcp_ai_peer_mcp_url |
string |
Remote MCP endpoint URL |
_wp_mcp_ai_peer_openapi_url |
string |
Remote OpenAPI spec URL |
_wp_mcp_ai_peer_jwks_uri |
string |
JWKS URI for token verification |
_wp_mcp_ai_peer_capabilities |
mixed |
Advertised capabilities |
_wp_mcp_ai_peer_regions |
mixed |
Serving regions |
_wp_mcp_ai_peer_data_tags / _wp_mcp_ai_peer_policy_tags |
mixed |
Data / policy tags |
_wp_mcp_ai_peer_quotas / _wp_mcp_ai_peer_price_hints |
mixed |
Quota and pricing metadata |
_wp_mcp_ai_peer_health_status |
string |
Health state (healthy, …) |
_wp_mcp_ai_peer_latency_p50 |
mixed |
p50 latency |
_wp_mcp_ai_peer_last_verified |
string |
Last verification timestamp |
_wp_mcp_ai_peer_last_error |
string |
Last verification error |
_wp_mcp_ai_peer_site_name / _wp_mcp_ai_peer_site_url |
string |
Remote site identity |
_wp_mcp_ai_peer_wellknown_url |
string |
/.well-known/ discovery URL |
_wp_mcp_ai_peer_verification_data |
mixed |
Verification payload |
Verified provisioning recipe (Design Stack)
This is the end-to-end path that actually works on the Design Stack deployment:
# 0. In the Design Stack WP container, wp requires --allow-root.
# (In this repo's own compose: docker compose run --rm wp-cli …)
# 1. Discover assignable slugs before assigning.
wp mcp-ai tool list # base registry: slug + enabled + capability
wp mcp-ai toolkit list # Pro toolkit settings keys
# 2. Create the record.
wp mcp-ai assistant create --title="Brand Assistant" --status=publish --porcelain
# → prints the new assistant ID (call it <id>)
# 3. Set runtime meta. The CLI's --model/--system-prompt write legacy keys the
# runtime ignores — set the _wp_mcp_ai_* keys explicitly:
wp post meta update <id> _wp_mcp_ai_provider openai
wp post meta update <id> _wp_mcp_ai_model gpt-4o-mini
wp post meta update <id> _wp_mcp_ai_temperature 0.7
wp post meta update <id> _wp_mcp_ai_system_prompt "$(cat assistant-system-prompt.md)"
wp post meta update <id> _wp_mcp_ai_classification internal
wp post meta update <id> mcp_ai_required_capability manage_options
# Tools is a serialized PHP array. wp post meta update would store a string,
# which breaks tool resolution — use wp eval for that one key:
wp eval 'update_post_meta(<id>, "_wp_mcp_ai_tools", array("web_search", "deep_research", "create_post"));'
# 4. Issue the credential (prints cred_xxxxx.SECRET exactly once).
wp mcp-ai credential issue <id> --porcelain
Verification checklist (what actually works)
MCP JSON-RPC handshake — POST /wp-json/mcp-ai/v1/mcp with
Authorization: Bearer <TOKEN>:
{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"zed","version":"1"}},"id":1}
Then tools/list — expect exactly the slugs you assigned (empty list ⇒
_wp_mcp_ai_tools was never set as an array).
REST chat smoke test (the reliable fallback when wp mcp-ai chat fatals):
curl -s -X POST http://localhost:8092/wp-json/mcp-ai/v1/chat \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{"assistant_id": <id>, "messages": [{"role":"user","content":"Reply with exactly: OK"}]}'
messages is required; assistant_id is optional (int or string);
optional options object accepts provider, model, temperature,
stream, response_format.
Inspect persisted config — wp post meta get <id> _wp_mcp_ai_provider
etc. Do not trust wp mcp-ai assistant get for meta (legacy-key caveat).
Detecting NV oOS agent enablement from a coding-agent session (Zed)
Added after a live Zed-session probe (2026-10). When a user asks "is agent
X available?" or "what tools does this MCP have?", NV oOS assistants never
appear under their server/assistant name — detect them by tool surface.
The two registries (do not conflate them)
- Zed agent registry —
list_agents_and_models. Lists only native Zed
sub-agents (e.g. Zed Agent) and their models. NV oOS assistants / MCP
servers are never listed here, even when fully connected. Absence here
proves nothing about the bridge.
- MCP tool servers — appear only as functions in your tool list, under
their tool names (e.g.
web_search_validated, list_ecas), never under
the server name (nv-oos-kate-agent, "ECA agent"). Map a name to its
tools via the group signatures below.
"Agent" in user speech almost always means "MCP server / assistant bridge",
not a registry agent. Translate the question to "which tool group is live?"
before answering.
Known tool-group signatures to look for
| Group |
Signature tools |
Notes |
| Research / web bridge |
web_search_validated, brave_web_search, brave_local_search, deep_research, semantic_content_search, verify_information, aggregate_research_data, extract_structured_data, generate_research_report, create_post_from_research |
16 tools observed in one session; web_search_validated is the cheapest probe |
| Image bridge |
generate_gemini_image_validated, generate_openai_image_validated, edit_gemini_image_validated, edit_openai_image, create_image_variation, product_actualization |
Usually exposed alongside the research bridge |
| ECA (school extra-curriculars) |
list_ecas, get_eca, create_eca, update_eca, enroll_student_eca, withdraw_student_eca, mark_eca_attendance, manage_eca_waitlist, get_eca_timetable, send_eca_notification, generate_eca_analytics, list_students, get_student |
26 tools observed; list_ecas is the cheapest probe |
| Design stack (may be absent) |
schedule_social_post, paper_store_*, remote_wp_connection, resize_image, remove_background |
Absence of one group does NOT mean the bridge is down — groups are exposed per assistant/session |
Detection procedure (in order)
- Inventory your tool list (the session function list) against the
signatures above. Presence of any signature tool ⇒ that assistant's MCP
is wired in.
- Probe with the cheapest read-only tool of the suspected group — e.g.
web_search_validated (max_results: 2) or list_ecas (defaults). A
live bridge returns real structured data: records, task_id, provider,
timestamps. An error or empty envelope means exposed-but-not-live.
- Re-probe, don't trust earlier checks. MCP connections refresh
mid-session. Observed:
list_available_toolsets worked on one call and
returned "No tool named … exists" minutes later while the underlying
tools stayed live. get_write_tools (where present) enumerates a
connected MCP's full mutating surface and doubles as a capability
snapshot (Cloudways: 188 write tools).
- Report precisely. Say "MCP server connected, verified live via
<tool> (<evidence>)" — never claim an assistant is absent just
because it is missing from list_agents_and_models.
Verified example (2026-10, single session)
list_agents_and_models ⇒ only Zed Agent (no nv-oos-* agents).
web_search_validated("…", 2) ⇒ real Brave results + task_id ⇒ NV oOS
research bridge (nv-oos-kate-agent) live.
list_ecas ⇒ 75 live ECA records from eca.directory ⇒ ECA MCP live.
- Cloudways:
get_write_tools ⇒ 188 write tools even after toolset-discovery
tools disappeared ⇒ connection still live.
Known issues (observed on Design Stack, 2026-09)
wp mcp-ai provider list and wp mcp-ai chat fatal (PHP 8) on builds
before the CLI fix: format_output() passed an inline array literal to
WP_CLI\Formatter's by-reference constructor, and chat constructed the
model router with zero args. Fixed in #6625 (merged to alpha-working;
ships after v1.1.79). Workarounds on older builds: provider config status
→ NV oOS settings page; provider connectivity →
wp mcp-ai provider test <slug>; chat → the REST smoke test above.
assistant create|update --model/--system-prompt write legacy keys the
runtime does not read (see CLI quirks). Always set _wp_mcp_ai_* explicitly.
--allow-root is required for wp inside the Design Stack WP container.
toolkit_cpt may be missing from tools/list on a given deployment
(Pro tool with a pro capability flag). Check availability before
scripting against it; WP-CLI + REST are the fallback.
Critical Rules
_wp_mcp_ai_tools must be a real PHP array (serialized). Set it with
wp eval / update_post_meta(), never wp post meta update (string).
mcp_ai_required_capability has no _wp_ prefix — unlike every other
assistant key. Getting this wrong silently falls back to default gates.
- Credential tokens print once (
credential issue --porcelain); never log
them or commit them. Hashes live in _wp_mcp_ai_credentials — never edit.
- Provider/model slugs must match
wp mcp-ai provider list and the model
catalog; a mismatched pair fails at runtime, not at assignment time.
- Peer records are only meaningful when
enable_federation_directory is on;
health is maintained by verification runs, not by editing the post.
- Verify with the checklist above after every change —
assistant get does
not show you the runtime configuration.
Common Mistakes
WRONG — assigning tools via wp post meta update
wp post meta update 42 _wp_mcp_ai_tools '["web_search", "deep_research"]'
// Stores a STRING. is_array() checks in tool resolution fail → tools/list [].
RIGHT — wp eval 'update_post_meta(42, "_wp_mcp_ai_tools", array("web_search", "deep_research"));'
WRONG — relying on assistant create --model to configure the runtime
wp mcp-ai assistant create --title="Bot" --model=gpt-4o
// Writes mcp_ai_model. The runtime reads _wp_mcp_ai_model → default model used.
RIGHT — create with --title/--status, then set _wp_mcp_ai_model via wp post meta update.
WRONG — trusting assistant get for configuration audits
wp mcp-ai assistant get 42
// Collects only mcp_ai_*-prefixed meta; misses _wp_mcp_ai_* keys entirely.
RIGHT — wp post meta get 42 _wp_mcp_ai_provider (one key at a time, or wp eval get_post_meta).
WRONG — exposing a credential in a Zed config file or chat log
// Tokens are bearer credentials; treat like API keys. Store via design-vault.
Cross-References
- Run
mcp-ai-wpoos-plugin for MCP bridge setup, JSON-RPC examples, and the
WP-CLI provisioning recipe with the chat REST smoke test.
- Run
design-pro-workflow-builder to create workflows that chain assistants.
- Run
design-pro-schedule-manager to schedule recurring assistant health checks.
- Run
design-vault to securely store credential tokens.
- Run
design-team-management to assign assistants to teams or roles.
- Run
design-crm if the assistant is used for CRM automation.
- Run
design-project-management if the assistant manages projects or tasks.
- Run
wp-security-audit on any assistant-facing endpoint — exposed
assistants are attack surfaces.
- Run
wp-security-secrets to audit credential handling.
- Run
design-elementor-mcp-connection to connect Elementor MCP servers to
an assistant via the MCP Apps metabox/slash-command (per-assistant remote
MCP tool bridging) — this skill covers assistant config, not MCP app
connections.
What This Skill Does NOT Cover
- MCP bridge tool calling mechanics — use
mcp-ai-wpoos-plugin for JSON-RPC.
- Chat UI configuration (shortcodes, Elementor widgets) — see the plugin's
chat UI documentation.
- Provider API key management — NV oOS Settings page or
design-vault.
- Vector store file upload and management — Files API tools.
- Agent memory system internals —
retrieve_agent_memory / store_agent_context.
- Workflow builder orchestration —
design-pro-workflow-builder.
- Peer wire protocol (SSE, message format) — this skill covers peer
configuration, not the transport.
- Multi-site WordPress network administration —
remote_wp_connection.
- MCP App connections to remote MCP servers (e.g. Elementor MCP) —
design-elementor-mcp-connection.
References
- Assistant CPT + meta constants:
includes/assistants/class-wp-mcp-ai-assistant-cpt.php
- Peer CPT + meta constants:
includes/class-wp-mcp-ai-ai-peer-cpt.php
- CLI commands:
includes/cli/class-wp-mcp-ai-cli-assistant-command.php,
…-credential-command.php, …-tool-command.php, …-provider-command.php,
…-chat-command.php, addons/pro/includes/cli/class-wp-mcp-ai-pro-cli-toolkit-command.php
toolkit_cpt MCP tool: addons/pro/includes/tools/infrastructure/class-wp-mcp-ai-pro-tool-cpt.php
- REST chat endpoint:
includes/rest/class-wp-mcp-ai-rest-chat-controller.php
- REST namespace (
mcp-ai/v1): includes/class-wp-mcp-ai-rest.php
- Credential store:
includes/class-wp-mcp-ai-credentials.php
1---2type: Skill3name: design-ai-assistant-admin4description: Manage AI assistant configurations and peer-to-peer mesh network connections in the NV oOS Pro Toolkit. Covers assistant creation, model configuration, provider setup, peer discovery, mesh networking, cross-assistant communication, and detecting from a coding-agent session (Zed) which NV oOS assistants / MCP servers are enabled. Use when creating or editing AI assistants, configuring model providers, setting up peer connections, managing mesh network topology, debugging assistant behavior, or answering "is agent X available" / "what tools does this MCP have".5license: Proprietary. See LICENSE.txt6metadata:7 source: https://skillmd.com/skills/nvdigitalsolutions/design-ai-assistant-admin8 type: Skill9---1011# NV oOS AI Assistant Administration1213> **Accuracy note (2026-09-15):** this skill was rewritten after a live14> verification pass against plugin v1.1.79 (`includes/assistants/`,15> `includes/cli/`, `includes/rest/`) and the Design Stack deployment. Every16> meta key, command, and route below is code-verified. The previous version17> of this skill documented `_assistant_*` / `_peer_*` meta keys that the18> plugin has never stored — do not use them.1920## When to use this skill2122Trigger when ANY of the following is true:2324- Creating, editing, or deleting AI assistant configurations.25- Changing an assistant's model provider (OpenAI, Gemini, Anthropic, Ollama, etc.).26- Configuring an assistant's system prompt, temperature, or tool access.27- Setting up or removing peer-to-peer federation records between WordPress sites.28- Listing all assistants with their current model, provider, and status.29- Querying which tools are enabled for a specific assistant.30- Debugging assistant behavior — checking configuration, tool access, or peer routing.31- Checking whether a specific NV oOS assistant / MCP server ("kate agent", "ECA agent", …) is enabled in the current editor session.32- Answering "is agent X available?" / "what tools does this MCP expose?" from inside a coding-agent session.33- Managing assistant-specific vector store or memory settings.34- Cloning an assistant configuration for testing or staging environments.3536## Mental model3738Two CPT-backed entity types, plus a small set of verified interfaces:3940```41AI ASSISTANT (CPT: mcp_ai_assistant) AI PEER (CPT: ai_peer)42├── title / post_status ├── title43├── _wp_mcp_ai_provider ├── _wp_mcp_ai_peer_mcp_url44├── _wp_mcp_ai_model ├── _wp_mcp_ai_peer_capabilities45├── _wp_mcp_ai_system_prompt ├── _wp_mcp_ai_peer_health_status46├── _wp_mcp_ai_tools (serialized slug array) ├── _wp_mcp_ai_peer_last_verified47├── _wp_mcp_ai_credentials (hashed tokens) ├── _wp_mcp_ai_peer_site_url48└── mcp_ai_required_capability └── … (see peer meta table)4950INTERFACES (in order of reliability):511. WP-CLI wp mcp-ai assistant|credential|tool|provider|chat|health|log …522. REST https://<site>/wp-json/mcp-ai/v1/chat + /mcp (JSON-RPC) + /tools533. Admin UI assistant CPT editor + federation pages544. toolkit_cpt MCP tool — Pro-only, not guaranteed to be exposed55```5657**Relationships:**5859- An **AI Assistant** (`mcp_ai_assistant`) is one row per assistant persona.60 Model, provider, prompt, temperature, and the assigned tool-slug array all61 live in `_wp_mcp_ai_*` post meta (plus `mcp_ai_required_capability`).62- An **AI Peer** (`ai_peer`) is a federation-directory record pointing at a63 remote MCP server: MCP/OpenAPI URLs, JWKS URI, capabilities, quotas, and a64 health status that is refreshed by verification runs. Peers only render in65 the admin federation page when `enable_federation_directory` is on.66- **`toolkit_cpt`** (`WP_MCP_AI_Pro_Tool_CPT`,67 `addons/pro/includes/tools/infrastructure/class-wp-mcp-ai-pro-tool-cpt.php`)68 is the generic CPT CRUD MCP tool (group `wordpress-core`, `pro` capability69 flag). It is NOT the single interface: it may be absent from a given70 deployment's `tools/list`. Always verify it exists before scripting against71 it; WP-CLI and the REST routes are the always-available paths.7273## WP-CLI command surface (verified against includes/cli/)7475| Command | Purpose |76|---|---|77| `wp mcp-ai assistant list [--status=any\|publish\|draft\|trash] [--format]` | List assistants (title, status, legacy model column — see quirk below) |78| `wp mcp-ai assistant get <id> [--format=json]` | Post-level details; only shows `mcp_ai_*`-prefixed meta (quirk below) |79| `wp mcp-ai assistant create --title=<t> [--status=publish] [--model] [--system-prompt] [--porcelain]` | Create assistant; `--porcelain` prints the new ID |80| `wp mcp-ai assistant update <id> [--title] [--status] [--model] [--system-prompt]` | Update assistant |81| `wp mcp-ai assistant delete <id> [--force] [--yes]` | Trash or permanently delete |82| `wp mcp-ai assistant export <id> [--file=<name.json>]` | Export config JSON (stdout or uploads/mcp-ai/exports/) |83| `wp mcp-ai assistant import [--file=<name.json> \| --stdin] [--porcelain]` | Import from exports dir or stdin |84| `wp mcp-ai credential list [<assistant-id>] [--format]` | List issued credentials |85| `wp mcp-ai credential issue <assistant-id> [--user=<id>] [--porcelain]` | Issue token; `--porcelain` prints `cred_xxxxx.SECRET` once |86| `wp mcp-ai credential revoke <assistant-id> <credential-id> [--yes]` | Revoke a token |87| `wp mcp-ai tool list [--status=enabled\|disabled] [--format=ids]` | **Discover assignable tool slugs** (registry + enabled state) |88| `wp mcp-ai tool enable <slug>` / `wp mcp-ai tool disable <slug> [--yes]` | Toggle global tool availability |89| `wp mcp-ai provider list` / `provider test <slug>` / `provider models <slug>` | Provider config status, connectivity test, model list |90| `wp mcp-ai chat "<message>" [--assistant=<id>] [--model] [--provider] [--stream] [--format=json]` | One-shot chat via the model router |91| `wp mcp-ai health` / `wp mcp-ai log` / `wp mcp-ai cache clear` / `wp mcp-ai version` | Diagnostics |92| `wp mcp-ai toolkit list \| enable <key> \| disable <key>` (Pro) | Pro toolkit settings keys (`enable_crm_toolkit`, …) — **not** assistant CRUD |9394There is **no** `wp mcp-ai peer` command — peer records are edited via post95meta or the admin UI. (Older versions of this skill claimed `peer list` /96`peer test`; those commands do not exist in v1.1.79.)9798### CLI quirks you will hit (code-verified)99100- `assistant create|update --model=…` and `--system-prompt=…` write legacy101 `mcp_ai_model` / `mcp_ai_system_prompt` meta keys. The chat runtime reads102 `_wp_mcp_ai_model` / `_wp_mcp_ai_system_prompt`, so those flags currently103 have **no runtime effect** — set the `_wp_mcp_ai_*` keys explicitly.104- `assistant list` reads `mcp_ai_model` (usually empty) and `assistant get`105 only collects meta keys starting with `mcp_ai_`, which misses every106 `_wp_mcp_ai_*` key. Inspect real config with `wp post meta get` instead.107- `wp mcp-ai provider list` and `wp mcp-ai chat` fatal on builds before the108 CLI fix in #6625 (see Known Issues).109110## Verified meta keys111112### `mcp_ai_assistant`113114Constants in `includes/assistants/class-wp-mcp-ai-assistant-cpt.php`:115116| Key | Type | Purpose |117|---|---|---|118| `_wp_mcp_ai_provider` | string | Provider slug (`openai`, `gemini`, `anthropic`, `deepseek`, `ollama`, …) |119| `_wp_mcp_ai_model` | string | Model identifier (`gpt-4o-mini`, `gemini-2.5-flash`, …) |120| `_wp_mcp_ai_temperature` | float | Sampling temperature |121| `_wp_mcp_ai_system_prompt` | string | Persona / system prompt |122| `_wp_mcp_ai_tools` | array (serialized) | Assigned tool slugs — must be a real PHP array |123| `_wp_mcp_ai_credentials` | array | Issued credentials (hashed). Never hand-edit |124| `_wp_mcp_ai_classification` | string | Information label; defaults to `internal` |125| `mcp_ai_required_capability` | string | Capability gate for tool calls — **no `_wp_` prefix** (`manage_options`, `edit_posts`) |126| `_wp_mcp_ai_vector_store_id` | string | OpenAI vector store for RAG |127| `_wp_mcp_ai_memory_files` | array | Memory file attachment IDs |128| `_wp_mcp_ai_corpus_name` | string | Corpus name for knowledge routing |129| `_wp_mcp_ai_tool_shortcuts` | array | Tool shortcut definitions |130| `_wp_mcp_ai_harness_profile` | array (JSON) | Agent-harness profile (memory summary etc.) |131132### `ai_peer`133134Constants in `includes/class-wp-mcp-ai-ai-peer-cpt.php`:135136| Key | Type | Purpose |137|---|---|---|138| `_wp_mcp_ai_peer_mcp_url` | string | Remote MCP endpoint URL |139| `_wp_mcp_ai_peer_openapi_url` | string | Remote OpenAPI spec URL |140| `_wp_mcp_ai_peer_jwks_uri` | string | JWKS URI for token verification |141| `_wp_mcp_ai_peer_capabilities` | mixed | Advertised capabilities |142| `_wp_mcp_ai_peer_regions` | mixed | Serving regions |143| `_wp_mcp_ai_peer_data_tags` / `_wp_mcp_ai_peer_policy_tags` | mixed | Data / policy tags |144| `_wp_mcp_ai_peer_quotas` / `_wp_mcp_ai_peer_price_hints` | mixed | Quota and pricing metadata |145| `_wp_mcp_ai_peer_health_status` | string | Health state (`healthy`, …) |146| `_wp_mcp_ai_peer_latency_p50` | mixed | p50 latency |147| `_wp_mcp_ai_peer_last_verified` | string | Last verification timestamp |148| `_wp_mcp_ai_peer_last_error` | string | Last verification error |149| `_wp_mcp_ai_peer_site_name` / `_wp_mcp_ai_peer_site_url` | string | Remote site identity |150| `_wp_mcp_ai_peer_wellknown_url` | string | `/.well-known/` discovery URL |151| `_wp_mcp_ai_peer_verification_data` | mixed | Verification payload |152153## Verified provisioning recipe (Design Stack)154155This is the end-to-end path that actually works on the Design Stack deployment:156157```bash158# 0. In the Design Stack WP container, wp requires --allow-root.159# (In this repo's own compose: docker compose run --rm wp-cli …)160161# 1. Discover assignable slugs before assigning.162wp mcp-ai tool list # base registry: slug + enabled + capability163wp mcp-ai toolkit list # Pro toolkit settings keys164165# 2. Create the record.166wp mcp-ai assistant create --title="Brand Assistant" --status=publish --porcelain167# → prints the new assistant ID (call it <id>)168169# 3. Set runtime meta. The CLI's --model/--system-prompt write legacy keys the170# runtime ignores — set the _wp_mcp_ai_* keys explicitly:171wp post meta update <id> _wp_mcp_ai_provider openai172wp post meta update <id> _wp_mcp_ai_model gpt-4o-mini173wp post meta update <id> _wp_mcp_ai_temperature 0.7174wp post meta update <id> _wp_mcp_ai_system_prompt "$(cat assistant-system-prompt.md)"175wp post meta update <id> _wp_mcp_ai_classification internal176wp post meta update <id> mcp_ai_required_capability manage_options177178# Tools is a serialized PHP array. wp post meta update would store a string,179# which breaks tool resolution — use wp eval for that one key:180wp eval 'update_post_meta(<id>, "_wp_mcp_ai_tools", array("web_search", "deep_research", "create_post"));'181182# 4. Issue the credential (prints cred_xxxxx.SECRET exactly once).183wp mcp-ai credential issue <id> --porcelain184```185186## Verification checklist (what actually works)1871881. **MCP JSON-RPC handshake** — `POST /wp-json/mcp-ai/v1/mcp` with189 `Authorization: Bearer <TOKEN>`:190191 ```json192 {"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"zed","version":"1"}},"id":1}193 ```194195 Then `tools/list` — expect exactly the slugs you assigned (empty list ⇒196 `_wp_mcp_ai_tools` was never set as an array).1971982. **REST chat smoke test** (the reliable fallback when `wp mcp-ai chat` fatals):199200 ```bash201 curl -s -X POST http://localhost:8092/wp-json/mcp-ai/v1/chat \202 -H "Authorization: Bearer <TOKEN>" \203 -H "Content-Type: application/json" \204 -d '{"assistant_id": <id>, "messages": [{"role":"user","content":"Reply with exactly: OK"}]}'205 ```206207 `messages` is required; `assistant_id` is optional (int or string);208 optional `options` object accepts `provider`, `model`, `temperature`,209 `stream`, `response_format`.2102113. **Inspect persisted config** — `wp post meta get <id> _wp_mcp_ai_provider`212 etc. Do not trust `wp mcp-ai assistant get` for meta (legacy-key caveat).213214## Detecting NV oOS agent enablement from a coding-agent session (Zed)215216> Added after a live Zed-session probe (2026-10). When a user asks "is agent217> X available?" or "what tools does this MCP have?", NV oOS assistants never218> appear under their server/assistant name — detect them by tool surface.219220### The two registries (do not conflate them)2212221. **Zed agent registry** — `list_agents_and_models`. Lists only native Zed223 sub-agents (e.g. `Zed Agent`) and their models. NV oOS assistants / MCP224 servers are **never** listed here, even when fully connected. Absence here225 proves nothing about the bridge.2262. **MCP tool servers** — appear only as *functions in your tool list*, under227 their tool names (e.g. `web_search_validated`, `list_ecas`), never under228 the server name (`nv-oos-kate-agent`, "ECA agent"). Map a name to its229 tools via the group signatures below.230231"Agent" in user speech almost always means "MCP server / assistant bridge",232not a registry agent. Translate the question to "which tool group is live?"233before answering.234235### Known tool-group signatures to look for236237| Group | Signature tools | Notes |238|---|---|---|239| Research / web bridge | `web_search_validated`, `brave_web_search`, `brave_local_search`, `deep_research`, `semantic_content_search`, `verify_information`, `aggregate_research_data`, `extract_structured_data`, `generate_research_report`, `create_post_from_research` | 16 tools observed in one session; `web_search_validated` is the cheapest probe |240| Image bridge | `generate_gemini_image_validated`, `generate_openai_image_validated`, `edit_gemini_image_validated`, `edit_openai_image`, `create_image_variation`, `product_actualization` | Usually exposed alongside the research bridge |241| ECA (school extra-curriculars) | `list_ecas`, `get_eca`, `create_eca`, `update_eca`, `enroll_student_eca`, `withdraw_student_eca`, `mark_eca_attendance`, `manage_eca_waitlist`, `get_eca_timetable`, `send_eca_notification`, `generate_eca_analytics`, `list_students`, `get_student` | 26 tools observed; `list_ecas` is the cheapest probe |242| Design stack (may be absent) | `schedule_social_post`, `paper_store_*`, `remote_wp_connection`, `resize_image`, `remove_background` | Absence of one group does NOT mean the bridge is down — groups are exposed per assistant/session |243244### Detection procedure (in order)2452461. **Inventory your tool list** (the session function list) against the247 signatures above. Presence of any signature tool ⇒ that assistant's MCP248 is wired in.2492. **Probe with the cheapest read-only tool** of the suspected group — e.g.250 `web_search_validated` (`max_results: 2`) or `list_ecas` (defaults). A251 live bridge returns real structured data: records, `task_id`, `provider`,252 timestamps. An error or empty envelope means exposed-but-not-live.2533. **Re-probe, don't trust earlier checks.** MCP connections refresh254 mid-session. Observed: `list_available_toolsets` worked on one call and255 returned "No tool named … exists" minutes later while the underlying256 tools stayed live. `get_write_tools` (where present) enumerates a257 connected MCP's full mutating surface and doubles as a capability258 snapshot (Cloudways: 188 write tools).2594. **Report precisely.** Say "MCP server connected, verified live via260 `<tool>` (`<evidence>`)" — never claim an assistant is absent just261 because it is missing from `list_agents_and_models`.262263### Verified example (2026-10, single session)264265- `list_agents_and_models` ⇒ only `Zed Agent` (no `nv-oos-*` agents).266- `web_search_validated("…", 2)` ⇒ real Brave results + `task_id` ⇒ NV oOS267 research bridge (`nv-oos-kate-agent`) live.268- `list_ecas` ⇒ 75 live ECA records from `eca.directory` ⇒ ECA MCP live.269- Cloudways: `get_write_tools` ⇒ 188 write tools even after toolset-discovery270 tools disappeared ⇒ connection still live.271272## Known issues (observed on Design Stack, 2026-09)273274- **`wp mcp-ai provider list` and `wp mcp-ai chat` fatal** (PHP 8) on builds275 before the CLI fix: `format_output()` passed an inline array literal to276 `WP_CLI\Formatter`'s by-reference constructor, and `chat` constructed the277 model router with zero args. Fixed in #6625 (merged to alpha-working;278 ships after v1.1.79). Workarounds on older builds: provider config status279 → NV oOS settings page; provider connectivity →280 `wp mcp-ai provider test <slug>`; chat → the REST smoke test above.281- **`assistant create|update --model/--system-prompt`** write legacy keys the282 runtime does not read (see CLI quirks). Always set `_wp_mcp_ai_*` explicitly.283- **`--allow-root`** is required for `wp` inside the Design Stack WP container.284- **`toolkit_cpt` may be missing** from `tools/list` on a given deployment285 (Pro tool with a `pro` capability flag). Check availability before286 scripting against it; WP-CLI + REST are the fallback.287288## Critical Rules289290- `_wp_mcp_ai_tools` must be a **real PHP array** (serialized). Set it with291 `wp eval` / `update_post_meta()`, never `wp post meta update` (string).292- `mcp_ai_required_capability` has **no `_wp_` prefix** — unlike every other293 assistant key. Getting this wrong silently falls back to default gates.294- Credential tokens print **once** (`credential issue --porcelain`); never log295 them or commit them. Hashes live in `_wp_mcp_ai_credentials` — never edit.296- Provider/model slugs must match `wp mcp-ai provider list` and the model297 catalog; a mismatched pair fails at runtime, not at assignment time.298- Peer records are only meaningful when `enable_federation_directory` is on;299 health is maintained by verification runs, not by editing the post.300- Verify with the checklist above after every change — `assistant get` does301 not show you the runtime configuration.302303## Common Mistakes304305```306WRONG — assigning tools via wp post meta update307wp post meta update 42 _wp_mcp_ai_tools '["web_search", "deep_research"]'308// Stores a STRING. is_array() checks in tool resolution fail → tools/list [].309RIGHT — wp eval 'update_post_meta(42, "_wp_mcp_ai_tools", array("web_search", "deep_research"));'310311WRONG — relying on assistant create --model to configure the runtime312wp mcp-ai assistant create --title="Bot" --model=gpt-4o313// Writes mcp_ai_model. The runtime reads _wp_mcp_ai_model → default model used.314RIGHT — create with --title/--status, then set _wp_mcp_ai_model via wp post meta update.315316WRONG — trusting assistant get for configuration audits317wp mcp-ai assistant get 42318// Collects only mcp_ai_*-prefixed meta; misses _wp_mcp_ai_* keys entirely.319RIGHT — wp post meta get 42 _wp_mcp_ai_provider (one key at a time, or wp eval get_post_meta).320321WRONG — exposing a credential in a Zed config file or chat log322// Tokens are bearer credentials; treat like API keys. Store via design-vault.323```324325## Cross-References326327- Run `mcp-ai-wpoos-plugin` for MCP bridge setup, JSON-RPC examples, and the328 WP-CLI provisioning recipe with the chat REST smoke test.329- Run `design-pro-workflow-builder` to create workflows that chain assistants.330- Run `design-pro-schedule-manager` to schedule recurring assistant health checks.331- Run `design-vault` to securely store credential tokens.332- Run `design-team-management` to assign assistants to teams or roles.333- Run `design-crm` if the assistant is used for CRM automation.334- Run `design-project-management` if the assistant manages projects or tasks.335- Run `wp-security-audit` on any assistant-facing endpoint — exposed336 assistants are attack surfaces.337- Run `wp-security-secrets` to audit credential handling.338- Run `design-elementor-mcp-connection` to connect Elementor MCP servers to339 an assistant via the MCP Apps metabox/slash-command (per-assistant remote340 MCP tool bridging) — this skill covers assistant config, not MCP app341 connections.342343## What This Skill Does NOT Cover344345- MCP bridge tool calling mechanics — use `mcp-ai-wpoos-plugin` for JSON-RPC.346- Chat UI configuration (shortcodes, Elementor widgets) — see the plugin's347 chat UI documentation.348- Provider API key management — NV oOS Settings page or `design-vault`.349- Vector store file upload and management — Files API tools.350- Agent memory system internals — `retrieve_agent_memory` / `store_agent_context`.351- Workflow builder orchestration — `design-pro-workflow-builder`.352- Peer wire protocol (SSE, message format) — this skill covers peer353 *configuration*, not the transport.354- Multi-site WordPress network administration — `remote_wp_connection`.355- MCP App connections to remote MCP servers (e.g. Elementor MCP) —356 `design-elementor-mcp-connection`.357358## References359360- Assistant CPT + meta constants: `includes/assistants/class-wp-mcp-ai-assistant-cpt.php`361- Peer CPT + meta constants: `includes/class-wp-mcp-ai-ai-peer-cpt.php`362- CLI commands: `includes/cli/class-wp-mcp-ai-cli-assistant-command.php`,363 `…-credential-command.php`, `…-tool-command.php`, `…-provider-command.php`,364 `…-chat-command.php`, `addons/pro/includes/cli/class-wp-mcp-ai-pro-cli-toolkit-command.php`365- `toolkit_cpt` MCP tool: `addons/pro/includes/tools/infrastructure/class-wp-mcp-ai-pro-tool-cpt.php`366- REST chat endpoint: `includes/rest/class-wp-mcp-ai-rest-chat-controller.php`367- REST namespace (`mcp-ai/v1`): `includes/class-wp-mcp-ai-rest.php`368- Credential store: `includes/class-wp-mcp-ai-credentials.php`