Using Discourse MCP to quickly build a theme

[sam (Sam Saffron)]

Often, the largest barrier to starting a community is “making it your own”.

You want, your font, your style to match your brand.

In this post I would like to cover what can be achieved in a quite straightforward way with:

• Discourse MCP - GitHub - discourse/discourse-mcp: MCP client for Discourse sites · GitHub
• A Pro or Business trial of Discourse
• An Open AI Codex subscription

I chose Codex here, cause the recently released GPT-6 Astra is an incredibly talented visual artist. Kimi K3 and Fable are also quite strong in this department, but for this demo I am using Astra.

Step 1 - Generate API key

Head to: your.site/admin/api/keys/new

Generate a global API key.

Security note: keep this key safe, consider revoking it once work is done, it provides unrestricted access to site.

Step 2 - Add Discourse MCP

In this tutorial I am using codex:

edit: ~/.codex/config.toml

[mcp_servers.discourse]
command = "npx"
args = [
  "-y",
  "@discourse/mcp@latest",
  "--toolsets",
  "all",
  "--allow-writes",
  "--site",
  "https://figment123.discourse.group",
  "--auth_pairs",
  '[{"site":"YOUR_SITE","api_key":"YOUR_API_KEY","api_username":"system"}]',
]

(note: the Codex does not let you choose which MCPs are enabled or disabled, everything in the config will be enabled. You can place a enabled = false to disable an MCP temporarily)

A noted about tools: The Discourse MCP supports 140+ tools, this config makes them all available. Modern harnesses such as Claude and Codex can handle this fine, that said many harnesses may struggle with a tool count this high - for example Grok build will require filtering)

Once you add Discourse MCP be sure to confirm that your agent can access it:

Step 3 - Give your Agent the tools it needs to do the job

An agent will perform significantly better, if it has:

1. Eyes, the ability to see its work. (playwright MCP, computer use, etc)
2. Context, the Discourse MCP helps, but so does the Discourse source code
3. Image generation - in case you need assets etc.

The ChatGPT app has a built in browser, be sure it uses it. Be sure to clone the discourse/discourse codebase and start your agent from the Discourse directory.

None of this is required but having it will result in significantly better results.

Step 4 - Give your agent intelligence and a clear brief

In this case given I want to see the very good results so I opted for GPT-6 Astra XHIGH.

Next up I wrote a small brief with my AI about what I wanted (A New Yorker community theme)

AI authored brief

Build The Salon, a polished Discourse theme that demonstrates how radically a customer can transform Discourse’s identity. The creative reference is The New Yorker: an editorial institution whose readers participate in the conversation. Create an original identity, not a replica—no borrowed logos or unlicensed proprietary typefaces. Use warm ivory (#F7F4ED), near-black ink (#20201E), restrained editorial red (#B52B32), fine rules, generous whitespace, expressive serif headlines, readable serif body text and compact sans-serif metadata. Monochrome illustrations should add wit and character. You have creative latitude to source, download or generate whatever assets the demo needs—fonts, illustrations, photography, avatars and icons—using appropriately licensed material and retaining attribution where required. Avoid generic SaaS cards, faux parchment and decorative clutter. Aim for a contemporary literary magazine with a living community inside it, not a stock forum with different colours.

You are explicitly authorised to stage the demo instance with the categories, topics, replies, fictional contributor profiles and supporting content needed to make the experience compelling. Preserve existing real content and keep fictional activity clearly identifiable as demo data. Create five editorial departments—The Commons, Arts & Letters, City Life, Science & Ideas, Table Talk—with distinctive descriptions and illustrations. Build a strong THE SALON masthead, a curated lead discussion, secondary headlines and a latest-conversations section. Seed thoughtful, varied discussions such as “When did every hobby become a side hustle?” and “What would actually change your mind?”, with convincing opening posts, substantive disagreements, short replies, quotations and well-chosen images. Populate enough content to demonstrate density, scrolling and navigation; don’t use repetitive filler or leave important screens empty. Every headline must open a real topic, and activity, reply counts and unread states must remain visible. Carry the identity through category lists, topic pages, search and the composer: opening posts should feel like beautifully typeset essays, while replies remain compact, usable conversations. Mobile should become a calm single-column experience, and dark mode should feel equally deliberate.

Inspect the target Discourse version and supported theme APIs before choosing implementation details. Prefer a maintainable theme and focused theme components; avoid core patches, unnecessary plugins, brittle DOM manipulation and invented functionality. Make editorial curation explicit and configurable. Work autonomously on reversible design, asset and staging decisions rather than asking for approval on every detail; establish the visual language with a representative homepage and populated topic page, then finish the supporting surfaces. Deliver an installable theme, required components, reproducible demo-content setup, asset provenance and concise installation instructions. Verify the result in a real Discourse instance on desktop and mobile, including keyboard navigation, contrast, unread states, search, quoting and composing. Capture the same staged community before and after applying the theme so the transformation is undeniable. The standard is a customer-ready demonstration—not a mockup, not just a beautiful homepage, but a coherent, working community with an entirely different sense of place.

• consult Discourse source as needed
• https://figment123.discourse.group/ is a demo site, you can do whatever you want with it, look at results as you go, enable the theme
• create topics as needed

Step 5 - Looking great !

One hour and 10 minutes later, Astra Xhigh is done.

A lovely New Yorker inspired theme.

The theme is not perfect, it has edge cases, I would recommend a Step 6 refine, where you paste in areas where the design is off and agent fixes. But as a starting point it is absolutely amazing we can do this today. It was not possible a year ago.

Example refinement in real time:

[EricGT]

Unless I am missing something, it looks like you created a custom AI agent harness to do this.

Since an AI agent harness is a broader concept than an AI coding harness—such as Claude Code, OpenAI Codex, or OpenCode—I went looking for a good introductory reference for anyone new to the terminology and hoping to clear away some of the fog:

What Is an AI Agent Harness?

If you only remember one line:

A model thinks. An agent acts. A harness keeps the agent from acting like an idiot.

---

Personally, I think we may be reaching the point where agents themselves are becoming less novel, while purpose-built AI harnesses are becoming the more interesting part of the story.

Instead of simply asking, “What agent are you using?”, the more useful question may increasingly be, “What harness have you built around it?”

[sam (Sam Saffron)]

Nope, I did build a custom harness but this is all vanilla ChatGPT app on Linux, Discourse MCP and a Discourse trial.

On Mac ChatGPT is even richer, it can control any app, so for example it could test in Firefox and Chrome during the process of building or even iPhone simulator.

My custom harness could achieve similar results, will post a different sample. https://chatgpt.com/download/

[satonotdead]

Just adding a new release I found interesting for anyone who wants to compare and evaluate an alternative outside of the US models:

DeepSeek V4.1 Flash matches GPT-6 Astra in design tests

[sam (Sam Saffron)]

I can definitely do a quick demo with it later, I doubt it is anywhere close to Astra

[merefield (Robert)]

Nice! I particularly relate to the headline article!

[satonotdead]

@sam

I doubt it is anywhere close to Astra

I was very skeptical at the time, and DeepSeek proved to me that it was worth it in its V4 version. GPT-6 Astra is a frontier model, but it’s very likely that DS 4.1 for tasks like this is can be a really good alternative.

[sam (Sam Saffron)]

Yeah to test fairly I need to redo the Astra work on my own harness then swap llm , so it will take a bit

[ducks (on the pond)]

@sam

• A Pro or Business trial of Discourse

this works for self hosters too

---

also, here’s my go at it. I will say I don’t love it for the exact project/community I’m working on but it did a good job none the less.

[putty]

This is awesome! I also appreciate the realism in your experience with the AI (“dude…” lol)

[sam (Sam Saffron)]

I ran a test run on DeepSeek 4.1 flash max.

Full transcript is here: https://gisthost.github.io/?28dedf78da999ccca5b5b4feb1d58fc9/index.html

This was a bit contaminated, cause I ran the test on a dv container and at some point the agent decided it might as well more efficiently use Docker to make the changes vs lean on our MCP.

For image generation I used Qwen 3 Image.

For eyes, I gave the agent the chrome-devtools-mcp. This can easily be configured to use chromium on Linux which tends to be my choice:

   "chromium-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--headless=true",
        "--executable-path=/usr/bin/chromium",
        "--chrome-arg=--no-sandbox",
        "--chrome-arg=--disable-dev-shm-usage"
      ]
    },

Entire run relied on DeepSeek 4.1 flash for both driver and sub agents.

I used term-llm.com to drive it in TUI mode:

Results:

Observations

The brief is critical, if you have a great brief the results will be great, if you have a poor brief you are at the mercy of the LLM. A great brief talks about the structure and colors and gives examples and so on.

DeepSeek 4.1 flash was very capable in this test and very cheap. At 99% cache read and only 2.8M read tokens, this would have cost about $1.52 off-peak or $3.04 in peak pricing. Astra is significantly more token efficient so this is unfair, but for context Astra pricing for a similar number of tokens would be $325

Conservatively even with token efficiency in mind I would guess you may be able to pull off a design like this in Astra for 50-100 dollars, getting it for 1 dollar 50 is impossible at current API costs.

I ran this on my OpenCode go plan, and did not even feel a small dent in my $10 a month plan:

A few things impressed me about this run, it was able to run unattended for hours. It acted on the EXACT same brief in the OP diligently and carefully. It did tried to address every point in the brief, it meticulously tested everything. The design was responsive, supported dark/light mode and more.

It got a ton right and the design is solid.

That said this is not GPT 6 Astra, the design feels more like a LLM design to me. The spacing, fonts and attention to detail was not the same as Astra. It is also very clear that it does not have the same fidelity around vision that Astra has, there were many obvious visual glitches after iteration 1, on the upside it was able to correct most of them when prompted.

It refused to fix this one for some reason:

But the rest of the quirks were handled fine by it.

The most impressive part of the build was how tidy it insisted on being

• It created a folder for evidence
• It attempted to cleanly engineer the theme and split it into lots of files and even test it

Overall, don’t expect Astra from a model 50/100 times cheaper, but as a tool it certainly can produce very interesting results for a fraction of the cost.

In retrospect, I would recommend building the theme directly in a dv container and then uploading cause you can run it safely in YOLO mode and the setup is very easy.

---

Will try to do some more experiments around this next week and post a few more examples. If you have a spectacular brief let me know.

Generally I use multiple LLMs from multiple vendors to build stuff, so a more “how I generally work” type of example may be interesting.

[mcwumbly (Dave McClure)]

@sam

Generally I use multiple LLMs from multiple vendors to build stuff, so a more “how I generally work” type of example may be interesting.

Would love to see something like that as well