Use Tidy with your AI assistant

Tidy speaks the Model Context Protocol (MCP), so connected assistants can find, read, create, and update your lists with your approval.

The canonical server URL is:

https://www.tidy.is/api/mcp

Connect Claude

Open Claude and go to Settings → Connectors.
Choose Add custom connector and paste the server URL above.
Select Connect, sign in with Tidy, and approve access.

Connect ChatGPT

Open Settings → Apps → Advanced settings and enable Developer mode.
Return to Apps, choose Create app, and enter the Tidy server URL.
Select OAuth, sign in with Tidy, and approve access.

Availability of custom write tools can depend on the ChatGPT workspace plan and its administrator settings.

Developer tools and scripts

CLI tools use a personal access token instead of the browser OAuth flow. Create a token under Tidy Settings → API tokens. The secret is shown once.

Claude Code:

claude mcp add --transport http tidy https://www.tidy.is/api/mcp \
  --header "Authorization: Bearer <your token>"

Codex:

[mcp_servers.tidy]
command = "npx"
args = ["-y", "mcp-remote", "https://www.tidy.is/api/mcp", "--header", "Authorization: Bearer <your token>"]

The same token works with the regular Tidy API:

curl https://www.tidy.is/api/v1/lists \
  -H "Authorization: Bearer <your token>"

Tool reference

The table below is generated from the live server registry so tool names and descriptions stay synchronized with the implementation.

Tool	Access	What it does
list_spaces	Read-only	List the user's spaces (workspaces). Lists and folders belong to a space.
list_folders	Read-only	List the user's folders. Folders group lists within a space.
list_lists	Read-only	List ALL of the user's lists (titles and metadata, no items) — renders an all-lists view in widget-capable clients. Only for overview requests; to look up one specific list by name use find_list, and use get_list for a list's items.
find_list	Read-only	Find lists by title and get their ids. Use this (not list_lists) when the user asks about one specific list by name; follow up with get_list. Falls back to returning every list when nothing matches, so you can pick the closest title.
get_list	Read-only	Get one list in full: metadata, sections, and items (including checked state, notes, tags, dates).
create_list	Write	Create a new list. Defaults to the user's default space and private visibility.
update_list	Write	Update a list: rename, edit description, set category or visibility, move to a folder/space, or toggle isFavorite.
delete_list	Destructive	Delete a list and all of its items. Irreversible from this interface — confirm intent first.
create_section	Write	Create a section (group) in a list. Items join it via sectionId, or use add_items with sectionTitle to create sections and items together.
update_section	Write	Rename a section (group) or change its position.
delete_section	Destructive	Delete a section (group). Its items stay in the list, ungrouped. Irreversible from this interface.
add_item	Write	Add ONE item to a list. For several items, or grouped content, use add_items instead. Optional: note (description), section, parent item (sub-item), quantity, link, type, due date, reminder, priority, tags.
add_items	Write	Add many items to a list in one call (up to 100, counting subItems). Preferred for imports and multi-item requests. Per item, set sectionTitle to group it — sections are created automatically in order of first use (or pass sectionId for an existing one) — and use subItems only for genuine subtasks. Repeat the call for content beyond 100 items.
update_item	Write	Update ONE item: title, note, checked state, section, parent, quantity, link, type, due date, reminder, priority, tags, or position. For changes to several items use update_items.
update_items	Write	Update MANY items in one call (up to 100): check off, uncheck, or edit several items at once. Always prefer this over repeated update_item/check_item/uncheck_item calls when changing more than one item — in widget-capable clients every single-item call renders its own list card.
check_item	Write	Mark ONE item as done (checked). For several items at once use update_items.
uncheck_item	Write	Mark ONE item as not done (unchecked). For several items at once use update_items.
delete_items	Destructive	Delete MANY items from a list in one call (up to 100). Prefer this over repeated delete_item calls when removing more than one item. Irreversible from this interface — confirm intent first.
delete_item	Destructive	Delete ONE item from a list. For several items at once use delete_items. Irreversible from this interface.
update_folder	Write	Rename a folder or toggle its isFavorite.
delete_folder	Destructive	Delete a folder (its lists move back to the space root).

Authentication and security

Chat applications use OAuth 2.1 with PKCE and act as the signed-in user.
Developer tokens are scoped, stored only as hashes, and revocable at any time.
Every connected-app change is recorded in the Tidy Logbook.
Requests are rate-limited per credential.

See the Privacy Policy and Terms of Service for how connected-app data is handled.