openEHR Discourse MCP Setup Guides

General Discussion
,
1

Following on from the conversation here about the Discourse MCP server, I thought it would be good to check it works for me.

It does work, but the Discourse MCP documentation for using it was so shambolically bad it actually made me question my life choices in getting involved with Discourse as a project! Put it this way - if you already knew how to do it, the documentation would have made you confused!

So, after quite a bit of unnecessary messing about, here is a tested guide for installing the 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.

Codex CLI :openai:

Prerequisites:

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

  1. The Discourse forum at https://discourse.openehr.org, which is the source of data and the target for actions.
  2. 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.
  3. Codex CLI, which is the client that connects to the MCP server and provides the interface for interacting with Discourse through the MCP API.

1. Generate the openEHR 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 https://discourse.openehr.org \
  --save-to /home/$USER/.codex/discourse-openehr-org.profile.json

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 /home/$USER/.codex/discourse-openehr-org.profile.json 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-openehr-org -- npx -y @discourse/mcp@latest --profile /home/$USER/.codex/discourse-openehr-org.profile.json

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 /home/$USER/.codex/discourse-openehr-org.profile.json 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

Confusingly, there are two places where settings are stored and the documentation for this is shockingly poor, 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. /home/$USER/.codex/config.toml - this is the Codex CLI configuration file, which includes the MCP server settings.
  2. /home/$USER/.codex/discourse-openehr-org.profile.json - this is the profile for the Discourse MCP server, which includes the API key and other settings for connecting to Discourse.

Codex CLI Settings (config.toml)

The settings for connecting to the MCP are in /home/$USER/.codex/config.toml and should look similar to this

# /home/$USER/.codex/config.toml
[mcp_servers.discourse]
command = "npx"
args = ["-y", "@discourse/mcp@latest", "--profile", "/home/$USER/.codex/discourse-openehr.profile.json"]

Codex MCP Settings documentation Model Context Protocol

Discourse MCP Settings (discourse-openehr.profile.json)

The settings for the Discourse MCP server itself are in /home/$USER/.codex/discourse-openehr.profile.json

# /home/$USER/.codex/discourse-openehr.profile.json
{
  "profiles": [
    {
      "site": "https://discourse.openehr.org",
      "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

Claude Code

Coming Soon

OpenCode

Coming Soon

1 Like