Docs · for AI agents
AICOMBase for AI agents.
Written for the AI that does the work — and for the person who sets it up. How to connect, the rules to follow, the tools, and what every answer means.
Connect
| Endpoint | aicombase.com/api/mcp — MCP over Streamable HTTP: JSON-RPC 2.0, one POST per request (protocol versions 2024-11-05 to 2025-11-25). |
|---|---|
| Authentication | Either an OAuth 2.1 sign-in — the app discovers it from the 401 answer (RFC 9728 metadata at /.well-known/oauth-protected-resource/api/mcp), registers itself (RFC 7591) and sends the person to AICOMBase to choose sites and permissions; PKCE S256 — or the header Authorization: Bearer aicb_agent_…, an AI connection key a person creates in AICOMBase (Keys → Generate New Key), shown once; treat it like a password. |
| Methods | initialize, tools/list, tools/call. A tool can also be called directly by name as the method, e.g. {"method": "sites.list"}. |
| Working rules | initialize returns them in instructions — tailored to the key’s mode. Follow them. |
POST https://aicombase.com/api/mcp
Authorization: Bearer aicb_agent_XXXXXXXXXXXX_…
Content-Type: application/json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sites.list","arguments":{}}}Apps that sign in — ChatGPT, Claude on the web and in its apps, Claude Code — need only the address: add a custom connector (or MCP server) with aicombase.com/api/mcp, and the person approves the access on AICOMBase's consent screen. Apps that take a key: add a remote MCP server with this address and the Authorization header. Apps that only run local MCP servers can use a bridge, for example:
npx -y mcp-remote https://aicombase.com/api/mcp --header "Authorization: Bearer YOUR_KEY"What the person sets up first
- At least one WordPress site connected to AICOMBase, running the AICOM plugin 3.21 or newer — see the setup guide: aicombase.com/docs/aicom
- An AI connection key with the sites (or site categories) and permissions the AI may use, and one tool mode: Full tool list, Tool Assist or MCPAssist. Tool Assist and MCPAssist are on every paid plan; a Free account gets them for its first 30 days.
- Optional key limits: allowed IP addresses, working hours, dry run only, expiry date.
- The work must also be allowed by the site’s policy in AICOMBase and by AICOM’s own settings on the site. The Capabilities page in AICOMBase shows, for every tool, whether it’s allowed and why not.
The rules
- Open a session before any action on a site: session.open(site_id, name, description). Name it after the job you were given; describe what you’ll do and why. Without it, every action fails with NO_ACTIVE_SESSION.
- One job, one session, one site. Keep doing the job’s work in that session; a session left idle closes after 2 hours.
- Check the result before you finish — read back what you changed — then session.close(site_id, outcome, summary) with a one-line summary.
- Stay within your key. A refusal (permission, policy, lock, key limit) is final: don’t retry it in a loop — tell the person what was refused and why.
- guard_challenge: explain honestly with guard.justify(challenge_id, justification), then repeat the exact same call. held_for_approval: a person decides — stop and report.
- Never ask for WordPress passwords. AICOMBase never needs them.
- Everything you do is recorded and a person can undo it. Say plainly what you did in the session summary.
How to do a job, by key mode
| Mode | Tools you get | A job, step by step |
|---|---|---|
| Full tool list | 20 tools: sites, sessions, capabilities, tasks, findings, notifications, incidents, site checks, guard.justify | sites.list → session.open → capabilities.list(site_id) → tasks.create(site_id, capability_id, tool_id, arguments, instruction) → tasks.get → session.close |
| Tool Assist | The same, plus tools.suggest — capabilities.list has no tool catalogue | sites.list → session.open → tools.suggest(site_id, request) → check the proposal → tasks.create → tasks.get → session.close |
| MCPAssist | 6 tools: sites.list, session.open, session.close, session.status, mcpassist, guard.justify | sites.list → session.open → mcpassist(site_id, instruction) — on need_information or ambiguous, call it again with the same task_id and the answer → session.close |
With MCPAssist, ask mcpassist in plain words when you need to know what to fix or what’s new: “What needs fixing on this site?”, “Tell me about finding <id>”, “Any new notifications?”. It answers without changing anything.
Work a person wrote for you: tasks.pending lists tasks people suggested to you; tasks.resolve picks the tool and runs it. Several steps that make one job: give them the same job_id, then call jobs.finish.
Tools
| Tool | What it does |
|---|---|
| sites.list | The sites your key can reach, with their status. |
| session.open / session.status / session.close | Open, check and close your session on a site. |
| capabilities.list | What a site can do: capabilities and their tools, with input schemas and required permissions (the catalogue only in Full tool list mode). |
| tasks.create | Run one tool on a site, with arguments matching its schema. |
| tasks.pending / tasks.resolve | Tasks people wrote and suggested to you; decide the tool and run it. |
| tasks.get | A task’s status and, once finished, its results or errors. |
| jobs.finish | Finish a multi-step job; may offer to save it as a reusable Skill. |
| findings.list / findings.get / findings.attempts | Problems the site checks found, one finding’s full detail, and past attempts to fix it. |
| audits.run / audits.status | Start a site check — or re-check specific findings after a fix — and follow it. |
| notifications.list / notifications.read | What’s new: findings, incidents, security alerts, task outcomes; mark them read. |
| incidents.list / incidents.get | Monitoring incidents and security alerts. |
| tools.suggest | Tool Assist: describe the job, get the right tool and arguments (nothing runs). |
| mcpassist | MCPAssist: say what you want; AICOMBase does it — or answers your question. |
| guard.justify | Answer an MCP Guard challenge. |
Answers and errors
| You get | It means | Do this |
|---|---|---|
| NO_ACTIVE_SESSION | No open session on that site. | session.open, then repeat the call. |
| guard_challenge | MCP Guard wants a reason before the action runs. | guard.justify(challenge_id, justification), then repeat the exact same call. |
| held_for_approval | A person must approve it. | Stop; tell the person. Don’t retry. |
| need_information / ambiguous | MCPAssist needs an answer to continue. | Call mcpassist again with the same task_id and the answer. |
| “isn’t available with this connection key” | That tool isn’t part of your key’s mode. | Use the tool the message names. |
| “doesn’t have the scope …” | Your key lacks that permission. | Tell the person; they can change the key. |
| Blocked by policy | The site’s policy doesn’t allow this work. | Tell the person; it’s their decision. |
| key_expired / ip_not_allowed | The key expired, or this IP isn’t allowed. | Stop; a person has to change or replace the key. |
| “… is included in every paid plan” | Tool Assist or MCPAssist on a Free account whose 30-day trial has ended. | Tell the person: they can upgrade, or switch the key to Full tool list. |
| outside_working_hours | The key only works in its hours (listing tools still works). | Try again inside the hours given. |
| Dry-run only key | Writes come back as a preview; tools that can’t preview are refused. | Report the preview; nothing was changed. |
| rate_limited (-32005) | More than 120 requests a minute with this key. | Wait a minute. |
| bad_bearer / missing_bearer | The key is wrong, revoked or missing. | Check the Authorization header. |