[Integrations](https://hourbun.com/integrations)

# [Connect Codex to Hourbun](https://hourbun.com/integrations/codex)

By Fred Wu, maker of Hourbun · Checked 13 November 2026 · [Report a mistake](mailto:support@hourbun.com)

## The short answer

Codex reads the token of an MCP server from an environment variable. Export a token of the page API & MCP as HOURBUN_TOKEN, then run codex mcp add hourbun with the address of the server and --bearer-token-env-var HOURBUN_TOKEN. Keep the export line in your shell profile, so that each new terminal has the token, and Codex tracks time and reads your projects as you.

## Where in the app

- API & MCP → New token
- API & MCP → Connect an AI assistant

## What you need

- A Hourbun account in an active workspace
- The Codex CLI in a terminal
- A token of the page API & MCP

## Set it up

The setup that the page API & MCP of Hourbun gives, with the address of the server. In a setup with a token, put the text of your token in the place of `YOUR_TOKEN`.

### Codex (Token)

Run it in a terminal, and keep the export line in your shell profile: Codex reads the token from HOURBUN_TOKEN.

[Docs of Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)

```
export HOURBUN_TOKEN="YOUR_TOKEN"
codex mcp add hourbun --url https://hourbun.com/api/v1/mcp --bearer-token-env-var HOURBUN_TOKEN
```

## What to ask

Ask in your own words: the assistant chooses the tools of Hourbun. Under each question, the tools that it calls. The tools of invoices and uninvoiced time answer for the owner and the admins.

- “Who am I in Hourbun, and which workspace is this?” Calls `whoami`.
- “Change yesterday's 2 hours on Website to 2.5.” Calls `list_time_entries`, then `update_time_entry`.
- “How many hours of Website are not invoiced yet?” Calls `get_uninvoiced`.
- “Track 3 hours on Website for today: API work.” Calls `list_projects`, then `create_time_entry`.

## The token in an environment variable

Codex keeps the name of the variable in its setup, not the token: `codex mcp add hourbun --url … --bearer-token-env-var HOURBUN_TOKEN` adds the server, and Codex reads `HOURBUN_TOKEN` when it connects. The setup exports `HOURBUN_TOKEN` first, so the command works in the same terminal.

Keep the export line in your shell profile, such as `~/.zshrc` or `~/.bashrc`, so that each new terminal has the token. Without it, Codex reaches Hourbun with no token, and Hourbun refuses each request. A profile is a file of your own: keep it out of a repository that others read.

When the token expires or you revoke it, make a new token and change the export line: the setup of Codex stays as it is.

## Make a token

On the page **API & MCP** of Hourbun, **New token** opens a form with the **Name**, the **Access** and **Expires after**. Name the token after Codex, so that the list says where it is used. **Read** lets Codex read your projects, clients, time and expenses; **Read and write** also lets it track time and use your timer. A token can end after 7, 30, 90 or 365 days, or never.

**Create token** shows the text of the token once, with **Copy token**. Under **Use it with an AI assistant**, choose Codex: its setup has the token in it, and **Copy setup** copies it whole. After **Done**, no page shows the token again: Hourbun keeps only a secure hash of it. The token acts as you, in this workspace and with your role, until it expires or you revoke it.

## What Codex can do

Hourbun has one MCP tool for each operation of its API, and Codex gets only the tools that your role and the access allow. With **Read**, it reads your projects, clients, tasks, time entries, timer and expenses. With **Read and write**, it also tracks time, changes and deletes your time entries, and starts, pauses, resumes, stops and discards your timer. Invoices and uninvoiced time are for the owner and the admins of the workspace: a member or a manager gets no tool for them.

Each tool calls what the REST API calls, so Codex gets the same answers, amounts and refusals as a script. An entry on an issued invoice, or an approved or submitted one, is locked, and a money field that your role does not see is left out. Hourbun keeps no prompt and no chat: a tool receives only its arguments.

## Stop the connection

Each token and each connection is in the list of the page **API & MCP**, with its access, its status and the day of its last use. **Revoke** ends it at once, and Hourbun refuses the next request of Codex. The owner and the admins of the workspace can revoke it too, and it stops when you leave the workspace.

## Questions and answers

### Where does Codex keep my Hourbun token?

In the environment variable HOURBUN_TOKEN of your shell, not in the setup of Codex. Keep the export line in your shell profile, and change it when you make a new token.

### Can I give Codex a token that only reads?

Yes. Choose Read for the token: Codex then gets only the tools that read, and changes no time and no timer. Read and write also lets it track time and use your timer.

### What happens when my Hourbun token expires?

Hourbun refuses each request of Codex with the token. Make a new token on the page API & MCP, and change the export line of HOURBUN_TOKEN.

## Sources

The setup of Codex follows its own documents, read on 13 November 2026:

- [Codex documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)

## Related

- [The MCP server in the API reference](https://hourbun.com/developers#mcp)
- [Time tracking in the help centre](https://hourbun.com/help/time-tracking)
- [Time tracking apps with an MCP server](https://hourbun.com/best/time-tracking-apps-with-an-mcp-server)
- [ChatGPT](https://hourbun.com/integrations/chatgpt)
- [Claude](https://hourbun.com/integrations/claude)
- [Claude Code](https://hourbun.com/integrations/claude-code)
- [Cursor](https://hourbun.com/integrations/cursor)
- [VS Code](https://hourbun.com/integrations/vscode)
- [Gemini CLI](https://hourbun.com/integrations/gemini-cli)
- [All integrations](https://hourbun.com/integrations)
