Connecting Outline Wiki with Codex via MCP

This guide extends the functionality of Outline Wiki by enabling integration with Codex, offering an alternative to services like Claude. The setup allows Codex, whether used as an App, CLI, or IDE extension, to leverage Outline's document management features through the MCP (Meta-Communication Protocol) server. This unified approach means a single configuration covers all Codex clients, streamlining the user experience.

Once configured, Codex can perform a range of operations within Outline. These include searching and listing documents, reading and editing existing content, creating new document collections, and moving files between collections. The integration essentially turns Codex into a powerful interface for managing your Outline knowledge base.

Prerequisites for Integration

Before proceeding with the integration, ensure you have the necessary software and access:

  • Codex App: You need to have the Codex application installed. This serves as the primary interface for interacting with the integrated system.
  • Node.js: A stable installation of Node.js is required. This is fundamental for running the MCP server and managing the integration scripts.
  • Operational Outline Wiki: A functional Outline Wiki instance is essential. The guide assumes you already have a working Outline setup that you can connect to.

Generating an Outline API Token

To allow Codex to interact with your Outline Wiki, you must generate an API token. This token acts as a credential, authenticating Codex's requests to your Outline instance.

Accessing Preferences

Log in to your Outline Wiki. Navigate to the settings by clicking the "..." icon next to your account name in the bottom left corner, then select "Preferences."

Creating a New Token

Within the preferences menu, find the section for API tokens or integrations. Click the option to create a new token. You will be prompted to name this token; a descriptive name like "Codex Integration" is recommended. After naming, click the "Create" button. Outline will then generate a unique API token. Crucially, copy this token immediately and store it securely. It will not be shown again after you leave this screen.

Assigning Permissions

When creating the API token, Outline allows you to specify the permissions it will have. For full functionality with Codex as described in this guide, ensure the token is granted broad access, including read, write, and create permissions for documents and collections. Review the available permission options carefully to match the capabilities you intend to use with Codex.

Setting Up the MCP Server

The MCP server acts as the bridge between Codex and Outline. It translates requests from Codex into actions that Outline can understand and vice versa.

Installation

First, you need to install the MCP server. Open your terminal or command prompt and run the following Node.js package manager command:

npm install -g @getoutline/mcp

This command installs the MCP server globally on your system, making it accessible from anywhere.

Configuration

Once installed, you need to configure the MCP server. This involves creating a configuration file, typically named mcp-config.json, in a directory of your choice. This file will contain sensitive information, so ensure it is stored securely and its permissions are restricted.

The configuration file requires details about your Outline instance and the API token you generated:


{
  "outline": {
    "url": "YOUR_OUTLINE_URL",
    "apiToken": "YOUR_OUTLINE_API_TOKEN"
  },
  "port": 3000
}

Replace YOUR_OUTLINE_URL with the base URL of your Outline Wiki instance (e.g., https://wiki.yourdomain.com) and YOUR_OUTLINE_API_TOKEN with the API token you copied earlier. The port specifies the port on which the MCP server will listen for incoming requests; 3000 is a common default.

Running the MCP Server

To start the MCP server, navigate to the directory where you saved your mcp-config.json file in your terminal and run:

mcp start --config mcp-config.json

The server will now be running and listening for connections on the specified port. You should see output indicating that the server has started successfully.

Configuring Codex to Use MCP

With the MCP server running, you can now configure your Codex clients to connect to it.

Codex App Configuration

Open the Codex App. Navigate to its settings or preferences, typically found under a "Settings" or "Integrations" menu. Look for an option to configure a custom API endpoint or MCP connection. Enter the URL of your running MCP server, which will be in the format http://localhost:3000 (or whatever port you configured). Save the settings.

Codex CLI and IDE Extension Configuration

For the Codex CLI and IDE extensions, the configuration process is similar. These clients usually read their configuration from environment variables or a dedicated configuration file. You will need to set an environment variable (e.g., CODEX_MCP_URL) to point to your MCP server's address (http://localhost:3000). Consult the specific documentation for the Codex CLI or your IDE extension for the exact method of setting this configuration.

Testing the Integration

After configuring Codex, it's time to test the integration. Try performing a few basic operations through Codex:

  • Search for a document: Use a Codex command to search for a document title you know exists in your Outline Wiki.
  • Read a document: Attempt to read the content of a specific document.
  • Create a new document: Use Codex to create a simple new document within an existing collection.

If these operations succeed, your Codex and Outline Wiki are successfully integrated via the MCP server. If you encounter errors, double-check your Outline API token, the MCP server configuration, and the Codex client settings for any typos or misconfigurations.

Advanced Operations and Use Cases

With the basic integration working, you can explore more advanced capabilities. Codex can be used to automate workflows involving your Outline documents. For instance, you could script a process to automatically generate meeting notes in Outline based on data from another application, or to maintain a consistent structure across your knowledge base by using Codex to move and organize documents programmatically. The possibilities are extensive, limited only by the API capabilities of Outline and the flexibility of Codex.

The ability to manage Outline documents directly from Codex means developers and technical writers can keep their documentation in sync with their code or other projects without context switching. This unified workflow is particularly beneficial for teams relying on a structured knowledge base for project management, technical documentation, or internal wikis.