---
title: "Add SuperEbook to Codex: CLI, IDE and desktop app"
description: "Add SuperEbook to Codex with one command and a browser sign-in, or an API key, shared by the Codex CLI, its IDE extension and the ChatGPT desktop app."
url: "https://www.superebook.ai/mcp/codex"
---

# Add SuperEbook to Codex. In the terminal, your editor and the ChatGPT desktop app.

Add SuperEbook’s MCP server to Codex and it can plan and write books in your SuperEbook account from your project’s notes. Codex keeps MCP servers in one config file that its CLI, its IDE extension and the ChatGPT desktop app share, so you add SuperEbook once.

## Before you start

- **A SuperEbook account with Starter, Pro or any credit pack.** SuperEbook’s Free plan doesn’t include connecting apps: [see plans](https://www.superebook.ai/pricing.md).
- **Codex, signed in:** the Codex CLI (run `codex` and choose Sign in with ChatGPT, or another sign-in), or the Codex extension in VS Code, Cursor or Windsurf.
- **A browser on the same computer** to sign in. Without one, such as over SSH, use an API key instead.

## Server URL

`https://www.superebook.ai/api/mcp`

## Sign in from the terminal

1. Add the server.

Codex saves it to `~/.codex/config.toml`, finds that SuperEbook supports signing in, and opens your browser. Keep the www.

```
codex mcp add superebook --url https://www.superebook.ai/api/mcp
```

2. Allow it on SuperEbook.

Sign in to SuperEbook if it asks. SuperEbook’s page asks “Connect Codex to SuperEbook?”, with no warning, because the app comes back to your own computer. Choose Allow.

3. Sign in again later with codex mcp login.

If the browser didn’t open, or the sign-in has run out, run `codex mcp login superebook`.

4. Check it.

`codex mcp list` shows it, and so does `/mcp` inside `codex`. Then ask Codex to plan a book.

The entry it writes is just the address:

```
[mcp_servers.superebook]
url = "https://www.superebook.ai/api/mcp"
```

## Or use an API key

For a computer with no browser to sign in from. The key stays in an environment variable; the file holds only its name.

1. Create an API key.

In SuperEbook, open [Settings → Connect apps](https://www.superebook.ai/settings?tab=apps) and choose Create API key. Name it after Codex, then copy it: you see the whole key only once, and it starts `ebk_live_`. It needs a verified email address.

2. Set it in the shell you start Codex from.

In your shell profile, for example. Replace `ebk_live_YOUR_KEY` with your key.

```
export SUPEREBOOK_API_KEY="ebk_live_YOUR_KEY"
```

3. Add the server with the variable’s name.

In `~/.codex/config.toml`, use this entry instead of the one above; one table per server name. Codex sends the key as `Authorization: Bearer …`.

```
[mcp_servers.superebook]
url = "https://www.superebook.ai/api/mcp"
bearer_token_env_var = "SUPEREBOOK_API_KEY"
```

Or the same from the command line:

```
codex mcp add superebook --url https://www.superebook.ai/api/mcp --bearer-token-env-var SUPEREBOOK_API_KEY
```

## In the IDE extension and the ChatGPT desktop app

If you added it above, there’s nothing more to do: the ChatGPT desktop app, the Codex CLI and the IDE extension share this configuration, so SuperEbook is already there.

1. Or add it from the extension.

Open the gear menu, choose MCP servers, then Add server. Name it superebook, choose Streamable HTTP and enter `https://www.superebook.ai/api/mcp`. Save, choose Restart extension, then Authenticate when the list shows the server needs a sign-in.

## Signing out or removing it

`codex mcp logout superebook` removes the sign-in Codex kept, and `codex mcp remove superebook` removes the server. To end the connection on SuperEbook’s side at once, disconnect Codex in [Settings → Connect apps](https://www.superebook.ai/settings?tab=apps).

## Try it

Once it’s connected, ask for a book in plain words. Planning is free, and the app is told to quote the price and wait for your yes before it writes.

- Read notes/talk.md and use SuperEbook to plan a lead magnet from it. Show me the plan first.
- Turn the README’s setup section into a SuperEbook how-to guide.
- What would a workbook cost in SuperEbook credits?
- Is my book written yet?

## If it doesn’t work

| What you see | Code | What to do |
| --- | --- | --- |
| Codex says the server may or may not require login |  | Run codex mcp login superebook to sign in. |
| Sign-in fails after choosing CIMD |  | SuperEbook doesn’t offer a client metadata document. Leave --oauth-client-registration out (the default, auto, registers dynamically), or pass dcr. |
| SuperEbook refuses the key |  | Check that SUPEREBOOK_API_KEY is set in the environment Codex starts from. An editor opened from the Dock or Start menu may not see what your shell profile sets: start it from a terminal, or sign in instead. |

For credits, limits and the other messages an app may relay, see [if something goes wrong](https://www.superebook.ai/mcp#troubleshooting).

## Questions

**Do I have to choose CIMD or DCR in Codex?** No. Leave Codex on its default: SuperEbook doesn’t offer a client metadata document (CIMD), so Codex registers itself (DCR). Forcing CIMD makes the sign-in fail.

**Why does SuperEbook’s page name Codex with no warning?** Codex signs in through an address on your own computer, so SuperEbook believes the name it registered under: Codex.

**Does ChatGPT on the web see the server I add to Codex?** No. ChatGPT on the web uses MCP servers through plugins, not Codex’s config: add SuperEbook there as a custom MCP server, as the ChatGPT guide shows.

**Will Codex wait while my book is written?** It doesn’t need to. Writing runs on SuperEbook and carries on without Codex; ask it later how far the book has got, or open the book in SuperEbook.

## Checked against OpenAI’s docs on October 18, 2026

- [Model Context Protocol, CLI (Codex docs)](https://learn.chatgpt.com/docs/extend/mcp?surface=cli): ~/.codex/config.toml shared by the CLI, the IDE extension and the ChatGPT desktop app, bearer_token_env_var, codex mcp list and login, /mcp, and OAuth registration with CIMD or DCR.
- [Model Context Protocol, IDE extension (Codex docs)](https://learn.chatgpt.com/docs/extend/mcp?surface=ide): adding a server from the extension’s gear menu, restarting it and authenticating.
- [Codex CLI (Codex docs)](https://learn.chatgpt.com/docs/codex/cli): signing in to the Codex CLI.
- [Codex IDE extension (Codex docs)](https://learn.chatgpt.com/docs/codex/ide): the Codex extension in VS Code and compatible editors.
- [codex-rs/cli/src/mcp_cmd.rs (openai/codex on GitHub)](https://github.com/openai/codex/blob/main/codex-rs/cli/src/mcp_cmd.rs): codex mcp add --url opening the sign-in, --bearer-token-env-var, logout and remove.

## More about connecting

- [Claude app](https://www.superebook.ai/mcp/claude-app.md)
- [Claude Code](https://www.superebook.ai/mcp/claude-code.md)
- [Cursor](https://www.superebook.ai/mcp/cursor.md)
- [VS Code](https://www.superebook.ai/mcp/vscode.md)
- [GitHub Copilot](https://www.superebook.ai/mcp/github-copilot.md)
- [Gemini CLI](https://www.superebook.ai/mcp/gemini-cli.md)
- [Zed](https://www.superebook.ai/mcp/zed.md)
- [Devin Desktop](https://www.superebook.ai/mcp/devin-desktop.md)
- [Other apps](https://www.superebook.ai/mcp/other-apps.md)