Installing BIThub Discourse MCP on Your Agents
BIThub can be connected to external AI agents through Discourse MCP.
MCP means Model Context Protocol. It is an open standard that lets AI applications connect to live systems, tools, data sources, and workflows.
Discourse MCP lets an AI agent connect to a Discourse forum like BIThub.
Use it when you want your own agent to search BIThub, read topics, inspect posts, retrieve guide context, and work with BIThub as a live knowledge source.
What This Does
Discourse MCP gives your agent a structured connection to BIThub.
Basic pattern:
your agent
→ Discourse MCP
→ BIThub
→ topics, posts, categories, tags, guides, and allowed resources
Without authentication, the agent can only use public/read-only access.
With authentication, the agent can access what that BIThub account can access.
With writes enabled, the agent may be able to create or modify forum content.
Start read-only.
Enable writes only after defining the exact scope of what the agent is allowed to do.
Why This Matters
BIThub topics are persistent AI workspaces.
A useful topic can hold:
- the task
- the context
- the discussion
- the links
- the files
- the corrections
- the outputs
- the final result
Discourse MCP lets external agents read that structured context.
This makes your agent BIThub-aware.
If you already understand MAS-Factory, this is the bridge:
Turn your agents into MAS-Factory originators by giving them MCP access to BIThub.
Read first:
Read This Before Giving an Agent Access
Agents need exact boundaries.
If you give an agent broad access and vague instructions, it may search the wrong category, summarize the wrong context, post in the wrong place, or expose private information publicly.
BIThub often routes serious work into private categories, private topics, and controlled member areas.
Do not assume the agent knows which BIThub space is safe.
Tell the agent exactly:
- what it may read
- what it may ignore
- what it may summarize
- what it may cite
- what it may post
- where it may post
- whether it may use private material
- whether it must ask before writing
Use narrow scopes first.
Account vs No Account
You can deploy and use Discourse MCP without a BIThub account.
That mode is limited to public/read-only access.
| Mode | Access |
|---|---|
| No account / no auth | Public read-only BIThub access |
| User auth | Access allowed by that BIThub user’s permissions |
| Admin auth | Administrative access; only for trusted operators |
| Writes enabled | Explicit write access; requires authentication and careful setup |
No account is enough for public guide reading.
A member account is required for member/private content.
Admin keys should not be used for normal agent work.
What Your Agent Can Read
Depending on permissions, Discourse MCP can expose forum context such as:
- categories
- tags
- groups
- topics
- posts
- public chat channels
- authenticated user resources when allowed
Exact access depends on:
- BIThub public permissions
- your BIThub account permissions
- category visibility
- private topic access
- MCP authentication
- write/read configuration
If the agent only sees public topics, that is expected without authentication.
Requirements
You need:
- Node.js
- an MCP-compatible agent or client
- command-line access
- BIThub URL
- optional BIThub authentication for private/member access
BIThub URL:
https://hub.bitwiki.org
Discourse MCP package:
@discourse/mcp
Official repository:
Install Read-Only Discourse MCP
Use read-only mode first.
npx -y @discourse/mcp@latest --site https://hub.bitwiki.org
This points Discourse MCP at BIThub.
Use this mode for:
- public topic search
- public guide reading
- public category inspection
- public knowledge retrieval
- agent research over public BIThub content
Read-only is the safe default. The official Discourse MCP package is designed to expose forum capabilities to agents, and write behavior must be enabled deliberately rather than assumed. ([GitHub][2])
Add BIThub MCP to an MCP Client
Most MCP clients use a JSON configuration.
Example:
{
"mcpServers": {
"bithub-discourse": {
"command": "npx",
"args": [
"-y",
"@discourse/mcp@latest",
"--site",
"https://hub.bitwiki.org"
],
"env": {}
}
}
}
Restart your MCP client after saving the configuration.
Your agent should now see the BIThub Discourse MCP server.
Recommended Read-Only Agent Scope
Use this for normal agents.
You have read-only BIThub access through Discourse MCP.
Use BIThub to search and read relevant public topics before answering BIThub-specific questions.
Do not claim access to private topics unless the MCP result actually returns them.
Do not write, post, edit, upload, message users, or modify BIThub.
Do not expose private, sensitive, or account-specific information.
When citing BIThub, return the topic title and link.
Good use cases:
- answer questions from public guides
- find relevant BIThub topics
- summarize public documentation
- compare public guide content
- prepare private drafts outside BIThub
- help users find where to go next
Authenticated Access
Use authentication only when the agent needs access beyond public content.
Authenticated access should use a normal BIThub user account with the minimum permissions needed.
Do not use admin credentials unless the agent is trusted, isolated, and explicitly doing operator work.
Example shape:
{
"mcpServers": {
"bithub-discourse-auth": {
"command": "npx",
"args": [
"-y",
"@discourse/mcp@latest",
"--site",
"https://hub.bitwiki.org",
"--auth_pairs",
"[{\"site\":\"https://hub.bitwiki.org\",\"user_api_key\":\"YOUR_USER_API_KEY\",\"user_api_client_id\":\"YOUR_CLIENT_ID\"}]"
],
"env": {}
}
}
}
Replace:
YOUR_USER_API_KEY
YOUR_CLIENT_ID
with your actual Discourse user API values.
Do not paste secrets into normal AI chat.
Do not commit credentials to GitHub.
Recommended Authenticated Agent Scope
Use this when the agent has member/private read access.
You have authenticated BIThub access through Discourse MCP.
Use only the permissions available to this account.
Prefer private categories and private topics when the task involves user work, drafts, strategy, client material, unpublished ideas, or sensitive context.
Do not quote private BIThub content into public outputs.
Do not summarize private topics for public posting unless explicitly instructed.
Do not post, edit, upload, or message users.
Before answering, identify whether the source material is public or private.
If the answer depends on private material, label it as private-context-derived and do not expose it outside the allowed audience.
This matters because BIThub deliberately separates public guides from private member workspaces.
Private content must not leak into public posts.
Write Access
Writes are disabled by default, but they can be enabled.
Only enable writes when the agent has a defined job and a safe posting boundary.
Write access can let an agent create or modify BIThub content.
Use write access for controlled workflows such as:
- drafting a reply in a specific topic
- posting a report into a private category
- creating an internal work topic
- updating a designated documentation topic
- publishing a reviewed summary after approval
Do not use write access for open-ended research agents.
Discourse MCP write access requires explicit configuration such as:
npx -y @discourse/mcp@latest \
--site https://hub.bitwiki.org \
--allow_writes \
--read_only=false \
--auth_pairs '[{"site":"https://hub.bitwiki.org","user_api_key":"YOUR_USER_API_KEY","user_api_client_id":"YOUR_CLIENT_ID"}]'
A Discourse MCP setup example for Codex shows the same required write posture: read_only: false, allow_writes: true, and authentication pairs. ([Discourse Meta][3])
Safe Write Pattern
Before enabling writes, decide how the agent will interact with BIThub.
Answer these:
What category may it post in?
What topic may it reply to?
Can it create new topics?
Can it use private categories?
Can it quote private material?
Can it mention users?
Can it upload files?
Can it edit prior posts?
Can it publish without review?
What should it do when unsure?
Default safe answer:
Private category only.
No public posting.
No user mentions.
No uploads.
No edits.
Ask before publishing.
Recommended Write-Enabled Agent Scope
Use this when writes are enabled.
You have write-enabled BIThub access through Discourse MCP.
You may only write inside the approved BIThub category or topic named by the user.
Default to private categories for drafts, analysis, strategy, client work, unpublished ideas, or internal workflow outputs.
Never post private information publicly.
Never create public topics unless the user explicitly says the content is public and ready to publish.
Before posting, show the exact draft and ask for confirmation.
Do not mention users unless explicitly instructed.
Do not upload files unless explicitly instructed.
Do not edit existing posts unless explicitly instructed.
If category visibility is unclear, stop and ask.
Public Posting Scope
Use this only for agents allowed to publish public content.
You may post only in the specified public BIThub category.
Before posting, verify that the content contains no private user data, credentials, unpublished strategy, confidential material, private category quotes, client information, or sensitive personal information.
You must show the final draft before posting.
If the content came from a private topic, do not publish it unless the user explicitly approves public release.
Private Workcell Scope
Use this for MAS-Factory-style private work.
You may create or reply only inside the specified private BIThub category or private topic.
Use the topic as a workcell.
Keep drafts, reasoning outputs, user corrections, and intermediate artifacts inside the private space.
Do not cross-post private content into public categories.
When the work is ready for public release, prepare a separate publishable summary and wait for approval.
Common Use Cases
Use BIThub Discourse MCP for:
- letting your agent search BIThub guides
- grounding answers in BIThub topics
- finding relevant platform references
- reading public documentation
- checking category and tag structure
- building BIThub-aware assistants
- connecting external agents to BIThub knowledge
- preparing drafts from existing topics
- creating private work topics with review
- routing work into BIThub after reading MAS-Factory
What Not To Do
Do not give agents more access than needed.
Do not use admin keys for normal agent work.
Do not enable writes for research-only agents.
Do not paste API keys into prompts.
Do not connect untrusted agents to private BIThub spaces.
Do not let an agent publish publicly without a review path.
Do not assume public read-only MCP can read private categories.
Do not let agents decide by themselves whether private content should become public.
Troubleshooting
The agent cannot find BIThub
Check that the MCP server is pointed at:
https://hub.bitwiki.org
The agent only sees public topics
That is expected without authentication.
Use user authentication only if the agent needs member/private access.
The agent cannot post
Writes are disabled by default.
Posting requires authentication plus explicit write flags.
The agent posted in the wrong place
Your scope was too vague.
Disable writes, narrow the allowed category/topic, and require confirmation before posting.
The agent exposes private information
Stop using write access immediately.
Rotate any exposed credentials if needed.
Move future work into private categories.
Give the agent a stricter scope.
The client does not show the MCP server
Restart the MCP client after editing the configuration.
Check that npx and Node.js are available.
The agent returns stale or weak answers
Tell it to search BIThub first and read the relevant topic before answering.
Related Guides
- MAS-Factory: How BIThub Turns Topics into Reusable Intelligence
- Getting Started with BIThub AI
- BIThub Participation Framework
- BIThub Alpha Limits
References
- Discourse MCP is here — Discourse Blog
- Discourse MCP is here — Meta Discussion
- Discourse MCP GitHub Repository
- Model Context Protocol Introduction
- Introducing the Model Context Protocol
- Installing Discourse MCP On Your Agents