Docs

Connect an AI assistant

Let your AI assistant read and add to your circles.

Trove has a remote MCP server so Claude, ChatGPT, Cursor, Claude Code, Grok, and other assistants can create and manage tasks in your circles. The assistant can do what you can do in the app, and nothing more.

A circle is shared. A house, a side business, a personal list, a community. Your list is yours. Mine is not a circle. It is every task with your name on it, across the circles you are in. Your private list is the personal circle made when you joined, usually named Personal.

There are two ways to connect.

1. OAuth. The assistant sends you to Trove to sign in and approve it. This is what Claude, ChatGPT, Cursor, Claude Code, and other directory connectors use. You can disconnect it later under Account, then Connect an AI assistant, then Connected apps.
2. A personal access token (trove_…). Use this when a client can send an Authorization header and cannot do OAuth.

Server

The server speaks Streamable HTTP. It does not keep a session between requests. Connect an assistant to this address.

https://mcp.troving.app/mcp

Connect with OAuth

The assistant discovers how to sign in from the server. You do not paste a token.

1. Add the server URL

   Paste the address above into the assistant.

2. Sign in when it asks

   The browser opens Trove at https://trove-app-one.vercel.app/oauth/consent. Sign in if you are not already.

3. Read the screen, then allow

   The page shows the assistant’s name and what it is asking to see. Allow, or don’t. The browser returns to the assistant, and it can then use your circles.

OAuth access is the same as yours. Approving an assistant does not give it anyone else’s circles. Disconnect it under Account → Connect an AI assistant → Connected apps → Revoke. That signs that assistant out. Your personal tokens are separate.

Claude

In Claude’s connectors directory, or in a custom connector, add the server URL. Claude uses OAuth. Do not put a personal token in the connector if the form is asking you to sign in.

ChatGPT

Add a custom connector, or the listed app once Trove is in the directory, with the server URL. ChatGPT requires OAuth. The consent page is the sign-in it is asking for.

Cursor

In Cursor’s MCP settings, add the server URL and leave the header empty so Cursor can sign you in. A personal token still works if you set the header instead. That config is further down.

{
  "mcpServers": {
    "trove": {
      "url": "https://mcp.troving.app/mcp"
    }
  }
}

Claude Code

Leave off the Authorization header. Claude Code asks you to sign in and opens the consent page. To use a personal token instead, add the header shown in the next section.

claude mcp add --transport http trove \
  https://mcp.troving.app/mcp

Grok

Add a custom connector with the server URL. When Grok asks to sign in, approve Trove on the consent page. If that form only has a header field, use a personal token.

Connect with a personal token

Replace trove_… with the token you create below. Send it on every request.

Authorization: Bearer trove_…

Create a token

1. Open Trove and go to Account → Connect an AI assistant.
2. Name the token after the app that will use it, for example Claude or Cursor.
3. Create it. The full token is shown once. Copy it then. Trove stores only a hash, so it cannot show the token again.
4. You can keep up to 10 active tokens. Revoke one you no longer use. Revoking takes effect on the next request and cannot be undone.

A token looks like trove_ followed by a random string. Treat it like a password. Do not commit it, paste it into a shared chat, or send it to anyone else.

Claude Code

claude mcp add --transport http trove \
  https://mcp.troving.app/mcp \
  --header "Authorization: Bearer trove_…"

Cursor

Add this to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project.

{
  "mcpServers": {
    "trove": {
      "url": "https://mcp.troving.app/mcp",
      "headers": {
        "Authorization": "Bearer trove_…"
      }
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "trove": {
      "type": "http",
      "url": "https://mcp.troving.app/mcp",
      "headers": {
        "Authorization": "Bearer trove_…"
      }
    }
  }
}

If that build only accepts a local command, use this instead. There is no space after the colon in the header.

{
  "mcpServers": {
    "trove": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.troving.app/mcp",
        "--header",
        "Authorization:Bearer trove_…"
      ]
    }
  }
}

Codex

[mcp_servers.trove]
url = "https://mcp.troving.app/mcp"
http_headers = { Authorization = "Bearer trove_…" }

If the gateway asks for an API key

Some gateways also want the project’s publishable key in an apikey header, beside Authorization. That key is already in the app. It is not a secret and it does not sign you in. The Trove token, or the OAuth access token, is what identifies you. Do not send a service role key.

Tools

Reads do not change anything. Completing a task can be undone, so it is not treated as destructive. Updating, assigning, and moving can remove notes, tags, or people, so those are. Inviting someone, and attaching a file from a web address, reach outside Trove.

Circles, status, and order

• Name a circle with circle_id or circle_name (the name is not case-sensitive, and it must be one of yours), or set personal: true for your private circle. Mine is not a circle. Ask for list_my_tasks, or set personal: true.
• Status is todo or done. Doing is not a status. Priority is low, medium, or high.
• For an owner or admin, priority also chooses a place in that circle’s order. High goes above the current top. Medium sits between the two central tasks. Low, or no priority, goes to the bottom. A member can set the label but cannot move an existing task. A new task with no priority starts at the bottom.
• Lists come back with rank. A larger rank sorts first, then the earliest due date (no date last), then the order they were added. Due filters are due_on, due_before, and due_after, as a calendar day (YYYY-MM-DD). A list returns 50 tasks unless you set limit (maximum 200).

People on a task

A task can have several people on it. assignee is one member id, a display name that is unique in that circle, "me", or null. assignees is a list of those same values. Pass one of them, not both. Either field replaces the whole set. An empty list, or assignee: null, clears everyone. Leave both out on create and the task is assigned to you. Leave both out on update and the current people stay. Results include assignees in order, and the first person again as assignee_id and assignee_name so older clients still see one. Your list includes a task when you are any of the people on it.

Tags and external ids

• Tags belong to one circle. Naming a tag creates it if needed. On update_task, tags replaces the whole set. An empty array clears them.
• external_id is a stable id from the source, such as a Notion page id or a Trello card id (1–200 characters). If you already created a task with that id, a later call returns that task and does not change it.
• create_tasks_bulk takes up to 100 tasks. More than that, and the whole call does nothing. If one item in a batch fails, earlier items in that batch stay, and the failure is reported.

Repeating tasks

create_task, create_tasks_bulk, and update_task take an optional repeat rule.

A week with no weekday uses the due date’s weekday. With no due date, it uses today’s weekday in UTC. That is the same rule the app uses.

Results from list, create, update, complete, assign, and move include the repeat fields and recurrence_series_id. The series id is shared by each occurrence. It is the first task’s id. The source id that stops a double completion is not returned, and it cannot be set.

complete_task, or update_task with status: done, marks that row done. If it repeats, the next to-do occurrence is added with the same title, notes, priority, tags, circle, people, and rule. The new occurrence starts at the bottom of the tasks that share its due date, so it does not keep the completed row’s place. The result is the completed row, not the new one. List the circle again to see the next occurrence. Photos stay on both, because the new row points at the same file. The external id stays on the original row only.

Inviting someone

invite_to_circle takes email, an optional role of admin, member, or viewer (the default is member), and an optional agent flag (the default is false). Creating the invite sends an email to that address. You can create 25 invites in 24 hours. Over that, the invite is not created and no email is sent.

agent: true marks the invite as a bot. When that invite is accepted, the new membership is stored as an agent. An existing member is not changed. You cannot invite someone as owner. One pending invite per email per circle. The link lasts 14 days. list_members includes is_agent for each person.

Creating a circle

create_circle takes name and an optional color. The name is trimmed and must be 1–80 characters. color is an accent name (sage, brand, moss, teal, dusk, lilac, plum, rose, terracotta, clay, ochre, honey) or a #rrggbb hex, the same values the app’s colour picker stores. It defaults to sage.

Circles do not have an emoji or a description. The new circle is not your personal circle. The result includes the circle id.

Photos and videos

add_task_attachment adds a file to a task so it shows in the app, in the order it was added. A task can have more than one. You must be able to edit the task (owner, admin, or member of its circle). A viewer cannot attach files. That is checked before anything is downloaded or stored.

Pass task_id, content_type, and one of url or data_base64. A URL must be a public or signed https address. The server downloads it. Private, local, and link-local addresses are rejected, including a redirect to one of those. data_base64 is the raw file, not a data: URL. filename is optional. Only an extension that matches the type is kept.

Allowed types are image/jpeg, image/png, image/webp, image/gif, image/heic, image/heif, video/mp4, video/quicktime, and video/webm. The bytes must actually be that type. The maximum size is 50 MB. The result includes the attachment id.

Moving a task

move_task is the only way to change a task’s circle. update_task will not do it.

• You must be allowed to edit the task where it is now. A viewer of that circle cannot move it. You must belong to the destination. A viewer of the destination can still receive a task.
• If someone on the task is not a member of the destination, their name comes off. They are not reassigned to you. If you move your own task into a circle you belong to, you stay on it.
• Tags from the old circle are removed. Photos and videos stay in the circle the task left. People who cannot see that circle cannot open them.

Try these

• What circles am I in?
• Create a circle called Garden, colour terracotta.
• Show my list that is due this week.
• Add “Call the plumber” to my personal circle, due Friday, assigned to me.
• Add “Take the bins out” to House every Wednesday.
• Attach this photo to the plumber task.
• Move everything in my Notion house list into my House circle. Use each Notion page id as the external id so we can run this twice.
• Move “Sketch the spring menu” from my personal circle into Household, and assign it to Sam.
• Invite sam@example.com to House as a member.

On a big import, keep each source id on the task. You can run the same prompt again and it will not make a second copy. Inviting someone emails them.

Security

• A personal token is hashed before it is stored. Trove cannot show it again.
• An OAuth access token is checked as a sign-in for this project, with an assistant client on it. A normal sign-in from the app, with no assistant attached, is not accepted. Scopes name you (openid, email, profile). They do not limit which of your circles the assistant can touch. Membership does.
• Requests run as you. Someone with access can create circles, create, edit, complete, assign, and move tasks, set or clear a repeat rule, attach photos and videos to tasks you can edit, and invite people to circles you administer. An invite sends an email. Completing a repeating task creates the next occurrence.
• They cannot see your tokens, members’ email addresses, or a circle you are not in. They cannot attach a file to a task they cannot edit.
• Revoke a personal token, or a connected app, under Account, then Connect an AI assistant. The next request with that token is refused. Revoking a connected app signs that assistant out.

Questions