Discourse MCP Setup in OpenAI Codex CLI

Wiki Users
, ,
1

I have been experimenting with Discourse MCP but found that the existing documentation in Meta for using it didn’t include anything for Codex CLI, and it was a little confusing working out which parts of the documentation would apply:

  • is it npx or npm install?
  • which parts of the setup are Codex and which parts are Discourse MCP?
  • where do I put the settings like read_only: false?

So, after quite a bit of messing about, here is a tested guide for installing the Discourse MCP into Codex CLI, and I will follow up in coming days with a guide for Claude Code CLI and opencode. If there are other MCP clients you’d like to use, let me know in the replies and I’ll try to help.

Prerequisites:

It’s important to realise that there are three separate components here:

  1. The remote Discourse forum, which is the source of data and the target for actions.

  1. The Discourse MCP server, which is an open-source locally-running tool that connects to Discourse and provides an API for Codex to interact with Discourse. This is installed as a STDIO server and launched on demand by Codex CLI.

  1. Codex CLI, which is the MCP client that connects to the MCP server and provides the interface for interacting with Discourse through the MCP API.

1. Generate the User API key

This will authenticate you to Discourse and this is how you will get your API key. npx will download and run the code, nothing needs to be installed in the traditional sense.

In a terminal, run:

npx @discourse/mcp@latest generate-user-api-key \
  --site =DISCOURSE-FORUM= \
  --save-to =MCP-CONFIG=

Approve the browser consent and copy back the encrypted data, which proves your ability to login and generates an API key which is saved to =MCP-CONFIG= for use by the MCP server.

The API key will have the same level of access to the forum that you have as a user.

2. Add the MCP server to Codex CLI:

Run this in a terminal (not in Codex CLI itself)

codex mcp add discourse \
  -- npx -y @discourse/mcp@latest \
  --profile =MCP-CONFIG=

It is installed as a STDIO server, so it will be launched on demand with npx by Codex CLI when you start up Codex CLI.

It is configured to use the profile at =MCP-CONFIG= and by default it is read-only.

3. Restart Codex CLI

Fully restart Codex so it reloads config.toml and the profile.

If it starts without errors there are no issues with the configuration and you should see the MCP server listed when you run the /mcp ‘slash’ command in Codex CLI.

In Codex CLI you can ask Codex to refer to this Discourse for information - especially information you have access to but is not public - this will verify it is connecting as you.

Editing Settings

At some point you might want to edit the settings in order to add the ability to write to Discourse, and you’d do this in the Discourse settings.

Confusingly, there are two places where settings are stored and between Codex docs and Discourse docs it’s really quite confusing, especially for working out which parts belong to Codex CLI and which are part of the MCP STDIO server itself.

There are two main files:

  1. =CODEX-CONFIG= - this is the Codex CLI configuration file, which includes the MCP server settings.

  2. =MCP-CONFIG= - this is the profile for the Discourse MCP server, which includes the API key and other settings for connecting to Discourse.

Codex CLI Settings

The settings for connecting to the MCP are in =CODEX-CONFIG= and should look similar to this. If you want to add options to the MCP server you add them here.

# =CODEX-CONFIG=
[mcp_servers.discourse]
command = "npx"
args = ["-y", "@discourse/mcp@latest", "--profile", "=MCP-CONFIG="]

Codex MCP Settings documentation Model Context Protocol

Discourse MCP Settings

The settings for the Discourse MCP server itself are in =CODEX-CONFIG=

# =MCP-CONFIG=
{
  "profiles": [
    {
      "site": "=DISCOURSE-FORUM=",
      "user_api_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "user_api_client_id": "discourse-mcp"
    }
  ]
}

Discourse MCP settings documentation reference GitHub - discourse/discourse-mcp: MCP client for Discourse sites · GitHub

2 Likes
Discourse MCP is here!