Connect Codex to Folio
To add Folio to Codex, export a personal token as FOLIO_TOKEN and add an [mcp_servers.folio] entry with your Folio's /mcp url and bearer_token_env_var to ~/.codex/config.toml. Or run codex mcp add folio --url, then codex mcp login folio, to sign in with OAuth. The CLI, the ChatGPT desktop app and the IDE extension share that file.
Updated
Read the runbook, write the summary
Ask:
Read the Release process page in Folio, then create a page called Release notes under Engineering with the items that are done.
Codex reads the page, creates the new page in the tree, and the commit shows up in Git history.
Connect
What you need
- Codex installed.
- A Folio token, created under the user menu, then API tokens.
- Your Folio address. Codex runs on your machine, so a Folio on a private network works.
Steps
Step 1: Put the token in an environment variable.
bashexport FOLIO_TOKEN=folio_pat_...Step 2: Add Folio to ~/.codex/config.toml. For one project only, use .codex/config.toml in a trusted project. Codex sends the variable's value as a Bearer header.
~/.codex/config.toml[mcp_servers.folio] url = "https://your-folio.example.com/mcp" bearer_token_env_var = "FOLIO_TOKEN"Step 3: Start Codex from the same shell, so it sees the variable, and ask your question.
Step 4: To sign in with your own account instead of a token, add the server by address and log in.
bashcodex mcp add folio --url https://your-folio.example.com/mcp codex mcp login folio
Try it against the demo
The demo does not issue personal tokens. Use the OAuth route with https://demo.foliowiki.online/mcp and sign in as Sam.
https://demo.foliowiki.online/mcpStep 1: Add the demo, then sign in.
bashcodex mcp add folio-demo --url https://demo.foliowiki.online/mcp codex mcp login folio-demo
The demo login is shared and the data resets every 24 hours, which also removes your connection. Pages written by other visitors are untrusted data, so do not connect an agent that has a shell or your own keys, and do not enter personal data. Requests are rate limited.
What the agent can do
Folio exposes 49 tools over MCP. Full reference.
| Reading (23) | What it does |
|---|---|
list_spaces | Spaces you can see, with your role in each |
list_tree | The page tree of a space |
list_templates | The page templates of a space |
search_pages | Full-text search across the pages you can open, with filters |
read_page | A page as Markdown, with its metadata; a form's fields, a canvas's outline, a base's YAML |
resolve_folio_url | A Folio link to the page it points at |
get_backlinks | Pages that link to a page |
page_history | The Git commits that touched a page |
page_at_sha | A page as it was at a given commit |
get_page_metadata | A page's headings, block ids, tags, properties and links |
list_unresolved_links | Links in a space that point at nothing |
list_orphans | Pages in a space that nothing links to |
get_graph | The link graph of a space, or the neighbourhood of one page |
list_tags | The tag tree of a space with page counts |
list_properties | The property keys in use, with their types and sample values |
query_base | The rows of an Obsidian base view |
folio_table_list | Data tables in a space |
folio_table_schema | A table's real columns, types and options |
folio_table_query | Table rows with filter, sort and search |
search | The same search under the name ChatGPT deep research looks for |
fetch | A page by the id that search returned, as Markdown |
check_page_writing_rules | The space's writing rules and a page's text, so the agent can check the page against them; nothing is changed |
list_comments | The inline comment threads of a page, with the text each is attached to and its status |
| Writing (26) | What it does |
|---|---|
create_page | A new document with text, or a table with columns |
update_page | Replace the text of a page; merges with live editing |
create_page_from_template | A new page copied from a template, with date, author and title filled in |
save_page_as_template | Copy an existing page into the templates of its space |
create_template | A new page template in the space's templates folder |
publish_artifact | An interactive HTML page, such as a Claude artifact, published as a page |
create_board | A whiteboard from a short description of boxes and arrows |
update_board | Replace a whiteboard's scene |
board_ops | Align, distribute, move or auto-layout board elements |
convert_canvas_to_board | An editable whiteboard made from an Obsidian canvas |
create_form | A form with its fields, and the table its answers go to |
update_form | Change a form's fields; the paired table follows |
folio_table_create | A table with an explicit schema |
folio_table_add_column | A new column |
folio_table_update_column | Rename a column or change its type or options |
folio_table_delete_column | A column and its values |
folio_table_save_view | A saved view with its filter, sort and hidden columns |
folio_table_delete_view | A saved view |
folio_table_insert | New rows |
folio_table_update | Cells, by row id or by filter |
folio_table_delete | Rows, by id |
rename_tag | Rename a tag across a space, in one commit |
set_page_properties | A page's properties, for any kind of page |
save_base | Create an Obsidian base or replace its YAML |
add_comment | A new inline comment thread on a passage of a page |
reply_comment | A reply in an existing comment thread |
- Reading needs the read scope. Writing needs write. With read only, every tool that changes something refuses to run.
- All 49 tools carry read-only or destructive annotations, so a client can ask before it writes.
- An agent cannot manage access rights, invite people, or rename and delete spaces. Those actions exist only in the browser.
- A write reaches the page file at once. The Git commit follows after about 90 seconds of quiet, so page history can lag behind an edit.
Security
- You sign in to your own Folio account and choose read, or read and write, on the consent screen. The connection acts with your rights and nothing more: a page you cannot open stays invisible to it.
- Writes are saved to Git history under your name.
- Access tokens last one hour and are renewed by a refresh token that rotates on every use. Folio stores only hashes of them.
- To disconnect, open the user menu, then API tokens, then Connected apps, and remove the app. Its tokens stop working immediately. Disabling the user does the same.
- An OAuth token works on /mcp only, not on the REST API.
- A personal access token carries the rights of the person who created it, narrowed by its scope. Give an agent its own Folio user with the editor role in the spaces it needs, and create the token there. Do not hand an agent an administrator's token.
- Use a read token when the agent only answers questions.
- The token is shown once. Keep it in an environment variable or the client's secret store, not in a file that goes to Git. Delete it under API tokens when you stop using it.
- Administrative routes are cookie-only: no token reaches them with any scope.
- Page content is data, not instructions. Folio's tool descriptions say so, but the real protection is rights. An agent that also has a shell and write access can be misled by a page someone else wrote, so give it the narrowest token that does the job.
Limits and honest notes
- The same ChatGPT account does not give you Folio in the ChatGPT chat. That is a separate route with OAuth: see the ChatGPT page.
Read more
Frequently asked questions
How do I add an MCP server to Codex?
Add a [mcp_servers.folio] table to ~/.codex/config.toml with url and bearer_token_env_var = "FOLIO_TOKEN", and export the token before starting Codex. For one project use .codex/config.toml in a trusted project. The CLI, the ChatGPT desktop app and the IDE extension share the file.
Can I sign in to Folio from Codex with OAuth instead of a token?
Yes: codex mcp add folio --url https://your-folio.example.com/mcp, then codex mcp login folio. Codex's documentation shows no command-line flag for a bearer token, so a token goes in config.toml.
Does the ChatGPT account that Codex uses also give me Folio in ChatGPT chat?
No. That is a separate route with OAuth; see the ChatGPT page.