Documentation

Memo / Todo MCP integration guide

Memo and Todo share the Streamable HTTP endpoints /mcp and /mcp/readonly. A credential's scopes determine which tools the client can see and call.

Quick start

1. Open Settings → Access tokens, create a token, and copy it immediately. It cannot be displayed again.
2. Select memo:read or todo:read for read access. Add the matching *:write scope for create, update, and delete operations.
3. Use https://<your-host>/mcp/readonly for read-only clients, or https://<your-host>/mcp when writes are needed.
4. Add Authorization: Bearer <your-token> to the client configuration. The client performs initialize and manages the session.

Tokens expire after 90 days by default; 30-day and non-expiring options may also be available. Revoke a token immediately if it may have leaked.

Cursor example

{
  "mcpServers": {
    "MeSQ-readonly": {
      "url": "https://<your-host>/mcp/readonly",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Access model

The X-MCP-Readonly: true header also forces read-only mode. OAuth and personal access tokens support the same Memo and Todo scopes.

Sessions

The response header Mcp-Session-Id identifies the session. Send it on later requests. Inactive sessions expire after about 30 minutes. Multi-instance deployments must route a session consistently by this ID.

Memo tools

Memo tools cover listing, keyword and semantic search, reading, creating, updating, soft deletion, tag management, and attachment upload/read. Use upload_memo_resource first, then pass its path to create_memo when creating a memo with attachments.

MCP attachment resources use memo://resource/{encodedPath}. Base64 reads are intended for files up to 5 MB; larger supported files should be read through MCP resources or their authenticated preview URL.

Todo tools

Use get_todo_context to discover spaces, columns, boards, and inboxes. Use create_todo_inbox_item for quick capture and create_todo_task for a specific board column. Todo attachments use todo://attachment/{encodedPath}.

Toolsets can be narrowed with X-MCP-Toolsets, including todos, todo-spaces, todo-columns, todo-inbox, todo-attachments, and todo-trash.

Content limits

Troubleshooting

The server does not currently expose MCP prompts or resources/subscribe. User-created Memo and Todo content is always returned in its original language.

REST API guide

Use REST for scripts and iPhone Shortcuts that call MeSQ without an MCP client. Create an access credential in Settings → Access credentials first, then replace the placeholders below.

• Base URL: https://<your-host>
• Authentication header: Authorization: Bearer <your-credential>
• Listing and reading require memo:read
• Creating requires memo:write
• Updating and moving to trash normally require both memo:read and memo:write, because the latest revision must be read before writing

List memos

curl -s 'https://<your-host>/api/toolkit/memo?deviceTimeZone=Asia/Shanghai' \
  -H 'Authorization: Bearer <your-credential>'

Read one memo

The response includes the memo's current revision. Use that value as expectedRevision for the next update or soft delete.

curl -s 'https://<your-host>/api/toolkit/memo/<memo-id>?deviceTimeZone=Asia/Shanghai' \
  -H 'Authorization: Bearer <your-credential>'

Create a memo

Use a new idempotency key for each logical create operation so a retry does not create a duplicate.

curl -s -X POST 'https://<your-host>/api/toolkit/memo' \
  -H 'Authorization: Bearer <your-credential>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <unique-key>' \
  -d '{"content":"Captured through the API","contentSource":"api"}'

In iPhone Shortcuts, configure Get Contents of URL with the same URL, POST method, headers, and JSON body.

Update a memo

Replace 123 with the latest positive integer revision returned by a read or previous write.

curl -s -X PATCH 'https://<your-host>/api/toolkit/memo/<memo-id>' \
  -H 'Authorization: Bearer <your-credential>' \
  -H 'Content-Type: application/json' \
  -d '{"content":"Updated content","expectedRevision":123}'

Move a memo to trash

curl -s -X DELETE 'https://<your-host>/api/toolkit/memo/<memo-id>' \
  -H 'Authorization: Bearer <your-credential>' \
  -H 'Content-Type: application/json' \
  -d '{"expectedRevision":123}'

Permanent deletion remains available in the authenticated MeSQ interface. Access credentials cannot call permanent-deletion endpoints.