Quick Start

Quick Start

This page takes you from a fresh install to a verified MCP call. It assumes the plugin is active and the official MCP Adapter 0.7.x is installed and active (see Installation).

1. Copy the endpoint

Open Agent Hub > Overview. The MCP endpoint field shows the full URL and Copy endpoint puts it on your clipboard (src/Admin/Pages.php).

https://example.com/wp-json/xnetvn-agent-hub-wp/mcp

The path is fixed: the server answers only the exact /xnetvn-agent-hub-wp/mcp route, and management routes live under /xnetvn-agent-hub-wp/v1 (src/Http/RouteMatcher.php, src/Rest/ManagementGate.php). While you are on Overview, select Check Authorization header to confirm your web server forwards the Authorization header to PHP; a host that strips it produces repeated 401 responses (docs/user-guide.md).

2. Create a key on your profile

1. Go to Users > Profile and find the Agent Hub API Keys section.
2. Select Create a key, then fill in:
   • Key name — a label you will recognise later.
   • Expires in days — defaults to 90 and cannot exceed the site's maximum lifetime (365 by default).
   • Risk tier — choose the lowest tier the client needs. read is enough for listing and reading; write adds changes; destructive adds deletion and similar actions.
   • Enabled toolsets — system is always on; enable only the packs the client needs (content, taxonomy, media, comments, users).
3. Optionally open Advanced settings to add allowed IP networks or block specific abilities.
4. Select Create key. Destructive and admin keys ask for your current password (docs/user-guide.md, src/Admin/Pages.php).

The key form only shows what you may choose: tiers at or below the site ceiling that your own capabilities support (admin appears only when the site enables it), and toolsets where you can use at least one ability. If the Agent Hub API Keys section is missing entirely, your account lacks the key-use capability — by default a user who can edit posts — or your role is outside the configured list (src/Admin/Pages.php, docs/en/architecture/overview.md).

The secret is displayed once in a dialog. Copy it before closing — the plugin stores only an HMAC-SHA256 hash, so it cannot be recovered (README.md, docs/en/adr/0004-key-model.md). The value has the form xnv_<key_id>_<secret> and is 60 characters long (src/Auth/TokenParser.php).

A scope can only narrow what your WordPress user may already do. Choosing read never grants read access you did not have, and a key's scope cannot be widened after creation — issue a new key with the wider scope instead (docs/user-guide.md, src/Domain/Scope.php).

3. Configure the client

Store the key in the client's secret store or an environment variable; never paste it into a page, log, screenshot or support report (docs/user-guide.md).

export MCP_ENDPOINT="https://example.com/wp-json/xnetvn-agent-hub-wp/mcp"
export MCP_API_KEY="paste-the-key-here"

The client must send the key as a bearer token:

POST /wp-json/xnetvn-agent-hub-wp/mcp HTTP/1.1
Host: example.com
Authorization: Bearer $MCP_API_KEY
Content-Type: application/json

Any client that can set that header works. If your host or client cannot send Authorization, the optional fallback header X-XNETVN-API-KEY is accepted while Accept the fallback API key header is on; turn it off if you do not need it (src/Admin/Pages.php, docs/user-guide.md). Browser-based clients on another origin also need that origin added under Settings > Network (docs/user-guide.md).

4. Make the first call

MCP is JSON-RPC 2.0 over HTTP. Start with tools/list; the response is narrowed to the tools your key's scope allows, not the full 62-ability catalog (src/Mcp/ServerGateway.php).

curl -sS -X POST "$MCP_ENDPOINT" \
  -H "Authorization: Bearer $MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

A working response lists tool objects. If you get 401, the key is missing, expired or revoked, or the server strips the header; if you get 403, the origin, transport, capability, tier, scope or IP allowlist refused the request before any tool ran (docs/user-guide.md).

Then ask the client to call the session tool. It returns your verified user, key scope, site and remaining request budget, and takes no parameters (src/Abilities/Packs/System/SystemPack.php):

{"jsonrpc":"2.0","id":2,"method":"tools/call",
 "params":{"name":"xnetvn-get-session-info","arguments":{}}}

The canonical ability name is xnetvn/get-session-info; MCP tool names replace / with - (docs/user-guide.md, src/Abilities/AbilityDefinition.php). Use the exact name the server advertises in the tools/list response rather than retyping it.

5. Verify the activity log

1. Open Agent Hub > Activity.
2. Filter by owner, key ID, ability, outcome or date range.
3. Confirm your calls appear with outcome success. Other outcomes are denied, error, invalid_input, rate_limited and auth_failed (docs/user-guide.md, src/Rest/AuditController.php).
4. Check the Transport column to see how the call arrived.

Activity rows record the time, request ID, transport, outcome, key, actor, ability, error code, duration, method, IP address, a truncated user agent and the names of top-level arguments — never argument values, bearer tokens, passwords, hashes or cookies (docs/user-guide.md). If a call fails, the row usually tells you whether policy denied it or the input was invalid.

Use Agent Hub > Tools to review which reviewed abilities a key can reach, with tier and toolset (readme.txt). When you are done testing, revoke the key on Agent Hub > Keys — revocation applies to the next request (docs/user-guide.md).

If something fails

Response	Likely cause	First action
401	Key missing, expired, revoked, or Authorization stripped	Recheck the key on Keys; use Check Authorization header on Overview.
403	Origin, transport, capability, tier or scope refusal	Read the message; lower the request scope or grant the capability the owner actually has.
429	Per-key or per-IP per-minute limit	Wait for Retry-After, then retry reads only.
503	Stored settings are invalid or unreadable	Re-save Settings; check the database if it repeats.

(docs/user-guide.md)

For the full settings reference, continue with Configuration.