Skip to content

Connect Claude Code to Folio

To add Folio to Claude Code, create a personal token under API tokens in Folio and run one claude mcp add command with the transport http, your Folio's /mcp address and an Authorization Bearer header. Run /mcp in a session to check the connection. Your code stays in the repository, your release process and decisions in Folio, and the agent reads both.

Sign-in: Token or OAuth

Updated

From a release to release notes in one request

Ask:

In the Acme Handbook space, find the release process page and tell me which checklist items are still open. Then create a page called "Release notes" under Engineering with a short summary of the roadmap items that are Done or In review. Then add a row to the Roadmap table: Public changelog page, status Planned, owner sam, team Design, due 2026-10-20, effort 2 days.

The agent reads the checklist, creates the page in the tree and adds the row. About a minute later the history of the page shows a normal Git commit. The same request is the one in the video.

Connect

What you need

  • Claude Code installed.
  • A Folio account. For a token, create it under the user menu, then API tokens. Scope write lets the agent edit; read is enough for questions.
  • Your Folio address. Claude Code runs on your machine, so a Folio on a private network works.

Steps

  1. Step 1: Create a token named Claude Code. Better still, create it under a separate Folio user for the agent, with the editor role only in the spaces it needs.

  2. Step 2: Add the server. Replace the address and the token.

    bash
    claude mcp add --transport http folio https://your-folio.example.com/mcp \
      --header "Authorization: Bearer folio_pat_..."
  3. Step 3: Or install the Folio Wiki plugin (foliowiki) from the repository. It carries the connection and a skill that tells the agent how to work with pages, tables and boards. In a session, the same two commands start with /plugin.

    bash
    claude plugin marketplace add evergreen-it-dev/folio
    claude plugin install foliowiki@foliowiki
  4. Step 4: For a team repository, put the connection in .mcp.json at the project root and keep the token in an environment variable, so it never reaches Git. Each person sets FOLIO_TOKEN in their shell. Use your own variable name: Claude Code blanks credential names it knows, such as ANTHROPIC_AUTH_TOKEN, in remote headers.

    .mcp.json
    {
      "mcpServers": {
        "folio": {
          "type": "http",
          "url": "${FOLIO_URL:-https://your-folio.example.com}/mcp",
          "headers": { "Authorization": "Bearer ${FOLIO_TOKEN}" }
        }
      }
    }
    bash
    export FOLIO_TOKEN=folio_pat_...
  5. Step 5: Check the connection. In a session, run /mcp: folio should be connected, with 49 tools. From the shell, claude mcp list shows the same.

    bash
    claude mcp list
  6. Step 6: Prefer to sign in with your own account instead of a token? Add the server without a header, then authenticate. Folio opens its sign-in and consent screen.

    bash
    claude mcp add --transport http folio https://your-folio.example.com/mcp
    claude mcp login folio

Try it against the demo

The demo does not issue personal tokens, so use the OAuth route: add https://demo.foliowiki.online/mcp, authenticate, and pick Sam on Folio's sign-in screen. Then ask for the open items on the Release process page.

Demo MCP address
https://demo.foliowiki.online/mcp
  1. Step 1: Add the demo, then sign in.

    bash
    claude mcp add --transport http folio-demo https://demo.foliowiki.online/mcp
    claude 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)
Reading (23)What it does
list_spacesSpaces you can see, with your role in each
list_treeThe page tree of a space
list_templatesThe page templates of a space
search_pagesFull-text search across the pages you can open, with filters
read_pageA page as Markdown, with its metadata; a form's fields, a canvas's outline, a base's YAML
resolve_folio_urlA Folio link to the page it points at
get_backlinksPages that link to a page
page_historyThe Git commits that touched a page
page_at_shaA page as it was at a given commit
get_page_metadataA page's headings, block ids, tags, properties and links
list_unresolved_linksLinks in a space that point at nothing
list_orphansPages in a space that nothing links to
get_graphThe link graph of a space, or the neighbourhood of one page
list_tagsThe tag tree of a space with page counts
list_propertiesThe property keys in use, with their types and sample values
query_baseThe rows of an Obsidian base view
folio_table_listData tables in a space
folio_table_schemaA table's real columns, types and options
folio_table_queryTable rows with filter, sort and search
searchThe same search under the name ChatGPT deep research looks for
fetchA page by the id that search returned, as Markdown
check_page_writing_rulesThe space's writing rules and a page's text, so the agent can check the page against them; nothing is changed
list_commentsThe inline comment threads of a page, with the text each is attached to and its status
Writing (26)
Writing (26)What it does
create_pageA new document with text, or a table with columns
update_pageReplace the text of a page; merges with live editing
create_page_from_templateA new page copied from a template, with date, author and title filled in
save_page_as_templateCopy an existing page into the templates of its space
create_templateA new page template in the space's templates folder
publish_artifactAn interactive HTML page, such as a Claude artifact, published as a page
create_boardA whiteboard from a short description of boxes and arrows
update_boardReplace a whiteboard's scene
board_opsAlign, distribute, move or auto-layout board elements
convert_canvas_to_boardAn editable whiteboard made from an Obsidian canvas
create_formA form with its fields, and the table its answers go to
update_formChange a form's fields; the paired table follows
folio_table_createA table with an explicit schema
folio_table_add_columnA new column
folio_table_update_columnRename a column or change its type or options
folio_table_delete_columnA column and its values
folio_table_save_viewA saved view with its filter, sort and hidden columns
folio_table_delete_viewA saved view
folio_table_insertNew rows
folio_table_updateCells, by row id or by filter
folio_table_deleteRows, by id
rename_tagRename a tag across a space, in one commit
set_page_propertiesA page's properties, for any kind of page
save_baseCreate an Obsidian base or replace its YAML
add_commentA new inline comment thread on a passage of a page
reply_commentA 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.
  • Claude Code can also read your repository in the same session, so you can ask it to compare the wiki with the code: read git log since the last tag and add to the release notes what the roadmap table is missing.

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

  • If a header is set and Folio rejects it, Claude Code reports a failed connection and does not fall back to OAuth. Check the token first.
  • The OAuth route, claude mcp login, is from Claude Code's documentation. We have run the token route, not this one.
  • Claude Code may ask before each tool call, depending on your permission settings. Folio's annotations let it tell reads from writes.

Read more

Frequently asked questions

How do I connect Claude Code to Folio?

Create a personal token under the user menu, API tokens, then run one command: claude mcp add --transport http folio https://your-folio.example.com/mcp --header "Authorization: Bearer folio_pat_...". Folio shows the token once. If you prefer your own sign-in to a token, add the server without the header and run claude mcp login folio.

Can Claude Code edit my Folio wiki, or only read it?

Both, depending on the token scope. A read token lets it search and read pages. A write token also lets it create and update pages and forms. Use read when the agent only needs to answer questions.

Can Claude Code see pages I am not allowed to open?

No. The token acts with the rights of its user, and the scope can only narrow them, never widen them. A restricted page stays invisible to the agent, and admin and access-management actions cannot be done with a token at all.

Where do Claude Code's edits end up?

In the page files. Folio writes the change to the file at once and records it as a normal Git commit, which can appear a little later. The page history shows what the agent changed, so you can review it or revert it.

How do I add an MCP server to Claude Code for a whole team?

Put the connection in a .mcp.json at the project root with the address and an Authorization: Bearer ${FOLIO_TOKEN} header, and let each person set FOLIO_TOKEN in their own shell. The token never reaches Git. Use your own variable name: Claude Code blanks credential names it knows, such as ANTHROPIC_AUTH_TOKEN.

Why does claude mcp list show Folio as failed?

Most often the token is wrong, expired or deleted. If a header is set and Folio rejects it, Claude Code reports a failed connection and does not fall back to OAuth. Create a new token under API tokens, or remove the header and use claude mcp login folio.