Docs · for AI agents
The AICOM plugin for AI agents.
AICOM also works on its own: an AI can connect straight to one WordPress site. Use this for a single site; use AICOMBase to work across many sites with central rules.
Connect
| Endpoint | POST YOUR-SITE/wp-json/aicom/v1/mcp — MCP JSON-RPC 2.0. Without pretty permalinks: POST YOUR-SITE/?aicom=1. Health check: GET YOUR-SITE/?aicom=1. |
|---|---|
| Authentication | Authorization: Bearer aicom_… or X-API-Key: aicom_… — a key the site’s administrator creates in WordPress: AICOM → API Keys → Generate New Key. Shown once. |
| Methods | initialize, tools/list, tools/call — plus tools/search (find tools by keywords) and tools/describe (one tool’s full schema). |
| Apache servers | If the Authorization header is stripped, use X-API-Key — or the administrator adds to .htaccess: SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 |
POST https://example.com/wp-json/aicom/v1/mcp
Authorization: Bearer aicom_XXXXXXXX_…
Content-Type: application/json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"wp.posts.list","arguments":{"post_type":"post","posts_per_page":10}}}What the site’s administrator sets up
- The free AICOM plugin, installed and active: wordpress.org/plugins/aicom
- An API key with only the permissions (scopes) the AI needs — presets such as Content Assistant or SEO Editor help.
- Optional key limits: allowed IPs or binding to the first IP, working hours, dry run only, a compact tool list for small models, an expiry date.
- Optional site-wide locks: Soft Lock (read-only) or Hard Lock (only public tools).
The rules
- Open a session before any change: session.open(name, description) — a short name and what you’ll do and why. Writes, deletions and admin actions without one fail with NO_ACTIVE_SESSION. Check with session.status; finish with session.close.
- Destructive tools need "confirm": true in the arguments.
- Add "dry_run": true to see what would change without changing anything.
- Add an "idempotency_key" to writes: if you retry, you get the first result instead of doing it twice.
- Locks win: Soft Lock allows reading only; Hard Lock allows only public tools such as server.status.
- AICOM backs up posts, terms and Elementor pages before changing them; a person can restore a whole session. You don’t need to back up yourself.
- tools/list only shows tools your key may call. Small models: use tools/search with plain words, then tools/describe for the one tool you need.
Errors
| Error | It means | Do this |
|---|---|---|
| AUTH_FAILED | Missing, wrong, expired or revoked key — or a request from an IP the key doesn’t allow. | Check the key; ask the administrator. |
| DENIED_SCOPE | Your key lacks the permission this tool needs. | Tell the person; don’t retry. |
| NO_ACTIVE_SESSION | A change was attempted without an open session. | session.open, then repeat. |
| CONFIRM_REQUIRED | A destructive tool was called without confirm. | Make sure the person wants it; add "confirm": true. |
| SOFT_LOCK_ACTIVE / HARD_LOCK_ACTIVE | The site is locked. | Stop; only the administrator can unlock it. |
| BLOCKED_WORKING_HOURS | Outside the key’s working hours. | Try again inside the hours. |
| RATE_LIMITED | Too many requests. | Wait, then retry. |
| TOOL_NOT_FOUND | No such tool — or not one your key can see. | Use tools/search to find the right one. |
| IDEMPOTENCY_IN_PROGRESS / IDEMPOTENCY_CONFLICT | The same idempotency_key is still running, or was used for different arguments. | Wait — or use a new key for a different change. |
When the site is connected to AICOMBase
Work sent from AICOMBase runs in AICOM sessions on the site too, marked as coming from AICOMBase, and is checked against AICOM’s own settings first. To work across many sites with one key, connect to AICOMBase instead: aicombase.com/docs/ai/aicombase