Install and troubleshoot the ToDoddle MCP
This guide covers local stdio MCP. Approved remote clients can use the hosted MCP private alpha without installing the package.
The ToDoddle MCP requires Node.js 20 or newer. Use the configuration generated by the one-time credential dialog; keep the values in the MCP host's environment configuration rather than source control.
{
"mcpServers": {
"tododdle": {
"command": "npx",
"args": ["--yes", "--prefer-online", "@krffl/tododdle-mcp@latest"],
"env": {
"TODODDLE_CLIENT_ID": "<client-id>",
"TODODDLE_CLIENT_SECRET": "<client-secret>"
}
}
}
}
Production TODODDLE_BASE_URL defaults to https://app.tododdle.com. Restart the MCP host after changing configuration, scopes, or grants. In Workspace Settings → Agent Connections, open Check setup, copy its read-only verification prompt, and run it from the configured agent. This proves the actual one-time credential, token exchange, scopes, project grants, and authorizing-user access together.
Local uploads need no extra configuration. The MCP accepts files from the operating system temporary directory. Stage temporary files there when an agent needs to upload them. The current user must own each file.
Set TODODDLE_UPLOAD_ROOTS only for special cases, such as Docker, sandboxes, or another specific directory whose contents you approve for upload. Use absolute paths. Separate multiple roots with : on macOS and Linux or ; on Windows.
Common failures:
unauthorized: confirm the client ID and secret; replace the old secret after regeneration and restart the agent.scope_required: enable the named capability.not_foundfor a known item: check the project grant and the creator's current access.permission_denied: the authorizing user cannot perform that action.conflict: reload and retry with the latestupdatedAt.rate_limited: wait until the supplied reset time.- Local path rejected: confirm the file is inside the managed staging directory or a configured optional root.
- Hosted client asks to authorize again: confirm the connection is enabled and your current workspace and project access still permit the grant.
Update an incompatible MCP
ToDoddle checks the MCP compatibility level on each External API request. A current MCP sends its package version and compatibility level. Older clients that do not send these headers still work during the staged rollout, but the API returns a warning header.
If an agent reports MCP_UPDATE_REQUIRED, run:
npx --yes --prefer-online @krffl/tododdle-mcp@latest
Then restart Codex or the other MCP host. The error includes the installed version, the minimum compatibility level, the update command, and this guide. Do not retry the same operation until the host has restarted.
Never paste credentials, ephemeral download URLs, or upload signatures into tasks, Notes, logs, or support messages. Rotate a secret if it may have been exposed.
Updated 2026-10-13. Owned by engineering.

