XenForo AI Connect — Installation & Setup Guide

Overview

Goldnat AI Connect for XenForo (add-on: chgold/AIConnect) turns your forum into a Servio Protocol tool server. The Free add-on ships 5 read tools — search threads, get a full thread, search posts, get a post, and identify the current user. The Pro add-on (chgold/AIConnectPro) adds 67 tools across eight permission groups — posting and moderation, engagement, profiles, conversations, attachments including PDF reading, and forum discovery.

What you get:

• 5 free tools — searchThreads, getThread, searchPosts, getPost, getCurrentUser
• Built-in translation — translation.translate + translation.getSupportedLanguages (XenForo-exclusive bonus)
• Pro upgrade — getForumList, createThread, replyToThread, editPost, sendConversation
• Future editions: xenforo-engagement-pro and xenforo-moderation-pro (Reactions, Reports, Ban)

Prerequisites

• XenForo 2.2.0 or higher
• PHP 7.2 or higher (8.1+ recommended)
• MySQL/MariaDB 5.7+
• Friendly URLs enabled (Options → Basic board information)
• HTTPS recommended
• “Manage add-ons” admin permission

Installation

1. Download the latest add-on ZIP from the official XenForo Resource Manager (or from your personal area at goldnat.ai).
2. Extract to src/addons/chgold/AIConnect/.
3. Admin → Add-ons → Install/upgrade an add-on — select chgold/AIConnect → Install.
4. Add-ons → chgold/AIConnect — verify status is “Active”.
5. Options → AI Connect → Verify manifest — clicking “Test” should return ✅.

Connecting to an AI Agent

1. Members → Your account → AI Connect Tokens (or /account/webmcp-tokens).
2. Generate Prompt — a ready-to-paste BBCode/Markdown block appears.
3. Copy and paste into your agent:
   • Claude Desktop: via the Goldnat MCP extension
   • goldnat.ai: add https://your-forum.example/ to your vault
   • ChatGPT / Gemini: connect directly to /api/aiconnect-manifest
4. OAuth PKCE runs in the browser → approve.

First Test

• “Who am I on the forum?” → xenforo.getCurrentUser
• “Search threads about AI” → xenforo.searchThreads with search=AI
• “What does post #3738 say?” → xenforo.getPost with post_id=3738

With Pro:

• “Create a new thread in the ‘General’ forum” → xenforo_pro.createThread
• “Reply to this post with the following message” → xenforo_pro.replyToThread

Reconnecting

Tokens valid for 30 days. Automatic refresh every hour. Manual reconnect:

1. Your account → AI Connect Tokens → Revoke the old token.
2. Generate Prompt again → paste into your agent.

Token Management

Like the other plugins: /account/webmcp-tokens page with 6 filters (Active / Renewable / Unused / Inactive / Revoked / All), bulk revoke, and last_used_ip + last_used_ua display.

Uninstalling the Add-on

1. Revoke all tokens

• Your account → AI Connect Tokens → Revoke All — kills every active agent session.

2. Disable the add-on

• Admin → Add-ons → chgold/AIConnect → Disable.
• The add-on stops working, but DB tables remain intact.

3. Uninstall the add-on

• Admin → Add-ons → chgold/AIConnect → Uninstall.
• XenForo prompts you to confirm removal of DB tables → confirm.

4. Remove the files

rm -rf src/addons/chgold/AIConnect/
# Also for Pro:
rm -rf src/addons/chgold/AIConnectPro/

5. Rebuild caches

php cmd.php xf-rebuild:caches

Common Troubleshooting

Error	Cause	Fix
Manifest not found	Friendly URLs disabled	Options → Basic → Enable Friendly URLs
Add-on files are missing	Files not extracted properly	Run xf-rebuild:addon via CLI
Route not registered	Rebuild missing	php cmd.php xf-addon:build-release chgold/AIConnect
Bearer token invalid	Prefix mismatch	Ensure the URL in the token matches the URL in the prompt

Support

Need help? Contact us and we’ll get back to you.

Video Tutorial (Coming Soon)

3-4 minute walkthrough: (A) Goldnat AI Connect on the Servio Protocol, (B) installing the add-on in XenForo admin, (C) connecting to an AI agent, (D) 3 typical forum queries.

What Pro adds

The free XenForo add-on gives AI agents read-only access: search threads and posts, read a thread, read a post, identify the connected account. That is five tools.

Pro adds 67 more, organised into eight groups. Every group is a separate permission entry, and every tool inside it has its own entry too — so you can allow replying without allowing deletion, or reading the forum structure without allowing anything to be written.

Pro ships as a separate XenForo add-on (chgold/AIConnectPro) that declares a dependency on the free chgold/AIConnect. It will not install standalone, and its tools are registered onto the core only when a valid licence is present.

The rule that governs everything

Every Pro tool runs as the connected member. XenForo’s own permission system does the enforcement — the add-on adds no privileged path of its own.

If a member cannot delete a post through the web interface, an agent connected as that member cannot delete it either. If a forum is invisible to them, it stays invisible to the agent. This is worth internalising before pointing an agent at a live forum: you are not granting the agent power, you are lending it an account.

Board administration — creating and deleting nodes, creating and deleting members, changing another member’s avatar — is deliberately not part of Pro. Those act on the board rather than as a member, and live in a separate add-on requiring the admin scope.

Tool groups

Group	Tools	Covers
Moderation	14	Lock, stick, feature, move, delete, solutions, thread type
Discovery	11	Node tree, board stats, recent and trending threads, tags, polls, reactions, profiles
Conversation	9	Read and manage conversations, invitations, alerts
Media	9	Attachments, PDF reading, thumbnails, your own avatar
Engagement	7	Reactions, votes, polls, read state
Profile	6	Profile posts, comments, your own profile
Core	6	Posting, conversations, forum list, member lookup
Writing	5	Thread tags, conversation replies and edits

Core

Available whenever any other group is enabled — the rest depend on it for identity and posting.

Tool	What it does
createThread	Create a thread. Accepts attachment_hash to attach a file in the same call
replyToThread	Reply to a thread, optionally with attachments
editPost	Edit a post. When passing attachment_hash, include existing attachments — anything omitted is treated as removed
sendConversation	Start a private conversation
getForumList	List forums the member can see
findUserByName	Look up a member by name prefix. Requires the member-list permission

Moderation

Standard moderator actions. Each is checked against the member’s moderator permissions for that specific node.

Tool	What it does
editThread	Change a thread’s title or prefix
lockThread / unlockThread	Close or reopen a thread
stickThread / unstickThread	Pin or unpin
featureThread / unfeatureThread	Add to or remove from featured content
moveThread	Move to another node
deleteThread / deletePost	Soft or hard delete
markSolution	Mark a post as the solution to a question thread
changeThreadType	Convert between discussion, question and article
deleteProfilePost / deleteProfilePostComment	Remove profile content

Discovery

Reading the shape of the forum. All read-only, all filtered by what the connected member may see — a private forum never appears.

Tool	What it does
listNodes	The node tree — categories, forums and pages
listNodesFlat	The same tree flattened, with depth, for rendering
getNode	A single node by ID
getForumNode	Forum details including counts
getForumStats	Board totals — threads, posts, members
getRecentThreads	Recently active threads, optionally scoped to a node
getTrendingThreads	Threads with the most replies in a time window
getThreadTags	Tags on a thread
getThreadPoll	A thread’s poll, responses and vote counts
getPostReactions	Reactions on a post, grouped by type, with the members who reacted
getUserProfile	A member’s profile and activity counters

On reaction counts. getPostReactions returns both total_reactions and reaction_score. They are different numbers. The score is weighted — XenForo assigns each reaction type a weight, and several default types weigh zero. A post with one “Wow” has a total of 1 and a score of 0. Use the total when you mean “how many people reacted”.

Conversation

Private conversations and alerts. Conversations are always loaded through the member’s own record, so an agent cannot reach a conversation the member is not part of.

Tool	What it does
getConversationMessages	Read messages in a conversation
markConversationRead	Mark as read
starConversation	Star or unstar
leaveConversation	Leave
inviteToConversation	Invite members. Anyone already present is reported separately rather than counted as invited
listAlerts / getAlert	Read alerts
markAlertRead / markAllAlertsRead	Mark alerts read

Media

Attachments and your own avatar. Note that changing another member’s avatar is an administrative action and is not in Pro.

Tool	What it does
uploadAttachment	Upload from a URL. Requires a target — node_id, thread_id, post_id or conversation_id — because XenForo derives the permission from the container, not from the member alone
deleteAttachment	Remove an attachment
listAttachmentsByKey	List attachments under an upload key
getAttachmentInfo	Metadata for one attachment
getPostAttachments	Attachments on a post
readAttachmentText	Read text content — plain text formats and PDF documents
getAttachmentThumbnail	Thumbnail URL
uploadMyAvatar / deleteMyAvatar	Your own avatar

Reading PDFs. Extraction is built into the add-on — nothing needs installing on your server. Scanned, image-only PDFs contain no text to extract; those are detected and reported as such rather than returning noise. If you need text from a scan, that is OCR, and it belongs on the agent’s side: the tools return a direct file URL, and models that read images can work from it.

Temporary attachments. A file that has been uploaded but not yet attached to anything is not “missing” — XenForo simply does not consider it viewable yet. Pass the hash returned by uploadAttachment to inspect it before attaching.

Engagement

Tool	What it does
reactToPost	React to a post
reactToProfilePost	React to a profile post
reactToConversationMsg	React to a conversation message
votePost	Vote on a post
votePoll	Vote in a poll
createPoll	Add a poll to a thread
markThreadRead	Mark a thread read

Two of these depend on forum configuration rather than on the add-on. createPoll requires the target forum to allow the poll thread type, and reacting to your own content is refused by XenForo itself.

Profile

Tool	What it does
postProfileMessage	Post on a member’s profile
editProfilePost	Edit a profile post
commentOnProfilePost	Comment on one
editProfilePostComment	Edit a comment
getProfilePosts	Read a member’s profile posts
updateMyProfile	Update your own profile

Writing

Tool	What it does
addThreadTags / removeThreadTags	Manage thread tags. Requires tagging to be enabled board-wide and the member to hold the tagging permission
replyToConversation	Reply to a conversation
editConversationMsg	Edit a conversation message
updateConversation	Update conversation settings

Permissions

Every tool has its own entry under Groups & Permissions → AI Connect, grouped into the eight sets above. Each set also has a master switch: denying it disables everything beneath it in one action.

A practical starting point is to enable Discovery and Core for a general account, and add Moderation only for an account that already moderates.

After installing or upgrading, tools may return a permission error until XenForo rebuilds its permission cache. On an active forum this resolves itself within minutes. If background tasks are disabled on your board, rebuild permissions manually from the control panel. This is not a fault in the add-on, but it looks like one if you are not expecting it.

Licensing

Licences are managed at goldnat.ai.

1. Setup → Options → AI Connect Pro License
2. Paste your licence key and save
3. Click Check licence now

A licence is bound to one domain, matched against your boardUrl. If you move the forum or run staging separately, change the licensed domain from your account page.

If the Pro tools do not appear at all, the licence is the first thing to check: without a valid one the tools are never registered, so they are absent from the manifest rather than failing when called.

Requirements

• XenForo 2.2+, PHP 7.2+
• The free AI Connect add-on, version 1.2.40 or later