API & MCP docs

Streamable HTTP, stateless, at https://mcp.getnido.dev/mcp.

POST https://mcp.getnido.dev/mcp
Authorization: Bearer <api_token | oauth_access_token>
Content-Type: application/json

• POST /pair — AI entry point: redeem an invite token for an api_token.
• GET / — human-readable server info.
• GET /.well-known/oauth-protected-resource — RFC 9728 metadata (OAuth discovery).

Two credentials are accepted on POST /mcp and the REST API: a static api_token, or an OAuth 2.0 access token. Write tools require the write scope.

Invite / pair flow (static token)

1. The human shares an invite link for the household: https://getnido.dev/invite/<token>.
2. The AI redeems it (each attempt spends one use of the invite):

curl -X POST https://mcp.getnido.dev/pair \
  -H 'Content-Type: application/json' \
  -d '{"token":"<64-hex-token-from-invite-link>"}'
# 201 -> { "api_token": "nido_...", "mcp_url": "https://mcp.getnido.dev/mcp", "instructions": "..." }

The api_token is shown only once and does not expire; only the household owner can revoke it. If /pair answers INVITE_MAX_USES, INVITE_EXPIRED or INVITE_REVOKED, ask the human for a new invite link. Reusing the same invite returns the same api_token (idempotent, so a retry never creates a duplicate agent); unused pair tokens are removed after 24 h.

Permissions

• Any member can create invites, create or archive lists, and add, check or remove items.
• Only the household owner can revoke invites or AI tokens, delete a list permanently, or delete the household.
• Removing an item is a soft delete: it stops appearing in lists but its assignment history is kept.

OAuth 2.0 + PKCE

1. Discovery: the 401 from /mcp carries WWW-Authenticate pointing at the RFC 9728 metadata, which names the authorization server at getnido.dev.
2. Authorization code + PKCE S256: GET https://getnido.dev/oauth/authorize (login + consent; the human chooses the household).
3. On the consent screen the human can narrow the grant to Read only even when the client requested write; the access token then carries only read.
4. Token exchange: POST https://getnido.dev/oauth/token with the code_verifier → access_token (≤ 1 h) + refresh_token (90 days, rotating).
5. Use it as Authorization: Bearer <access_token>; revoke at POST /oauth/revoke.

AS metadata (RFC 8414): GET https://getnido.dev/.well-known/oauth-authorization-server.

Dynamic registration (RFC 7591): POST https://getnido.dev/oauth/register (announced as registration_endpoint). Bootstrap document: GET https://getnido.dev/.well-known/muse-client.json.

19 AI-first tools. list and item accept an id or a name (server-side exact → fuzzy resolution).

Every tool is classified the way the Meta/Muse connector review requires. Read and Write travel in the MCP tools/list annotations (readOnlyHint / destructiveHint); Sensitive write is a documentation/portal designation that MCP annotations cannot express.

• Read — retrieves information without changing data or state: digest, notifications, lists, get_items.
• Write — creates, changes or deletes data: mark_notifications_read, create_list, archive_list, add_item, add_items, check_item, uncheck_item, remove_item, claim_item, assign_item, release_item, mark_purchased.
• Sensitive write — irreversible or consequential: create_invite (grants access to the household) and revoke_invite (deletes an invitation). These require explicit approval every time.

Write tools require the write scope; with only read they fail with a scope error. On the OAuth consent screen you can grant Read only even when the client requested write; the access token then carries only read. The platform (for example Muse) applies its own human-in-the-loop approvals on top.

Effects: archive_list hides without deleting, add_items is capped at 100, and invites carry expires_in/max_uses. Claim actions are append-only history: the latest row is the current holder, and claim_item requires releasing an item held by someone else. Every tool operates only inside the single granted household.

npx @modelcontextprotocol/inspector --cli https://mcp.getnido.dev/mcp --transport http \
  --method tools/list --header "Authorization: Bearer <token>"

npx @modelcontextprotocol/inspector --cli https://mcp.getnido.dev/mcp --transport http \
  --method tools/call --tool-name digest --header "Authorization: Bearer <token>"

Any MCP client with a Streamable HTTP transport works. Send Authorization: Bearer <token> and start with digest(). Native clients (no Origin) or Origin: https://getnido.dev are allowed; other origins get 403.

Base URL https://getnido.dev/api/v1, same Bearer authentication (OAuth access token or api_token).

curl https://getnido.dev/api/v1/households \
  -H "Authorization: Bearer <token>"

Who can use it

• Requires a Nido account with Google sign-in; there is no email/password or enterprise SSO.
• You must belong to a household; every action runs inside one household.
• Any member can create invites; only the household owner can revoke invites or AI tokens and delete the household.
• OAuth consent covers a single household per grant (separate grants for more households). The static api_token flow needs an invite link and spends one use; the token does not expire until the owner revokes it.
• Intended for users in the EU (Spain), under GDPR/LOPD.
• Plan caps and the daily MCP quota apply (the household starts on Free):

What it can do

• Reads and writes household lists and items through the 13 tools; list and item accept an id or a name.
• Write tools require the write scope; reads work with read.
• Effects: archive_list hides a list without deleting it; add_items is capped at 100; invites carry expires_in / max_uses.

What it does not do

• No calendar or reminders, no multiple households in a single grant, no account/household deletion, no billing, no file attachments, and no history export.
• It only accesses data of the household the grant belongs to (lists, items, members, invites, notifications/profiles); no other accounts.

• POST /mcp: 100 req/min per token → 429 with Retry-After.
• POST /pair: 10 attempts / 10 min per IP.
• OAuth (/oauth/token, /oauth/revoke, /oauth/authorize): 10 / 10 min per IP.
• Missing or invalid/revoked Bearer → 401 {"error":{"code":"UNAUTHORIZED"}} with WWW-Authenticate for OAuth discovery.
• MCP responses are compact; tool errors set isError: true.
• Activity history is deleted after the plan window (Free 7 days, Plus 30, Pro 90); get_activity never returns older entries.

Data handling & support: when you connect Nido through an assistant or platform (for example Meta/Muse), we process your data only within the scopes you authorize and as needed to fulfil your request — see the Privacy Policy. For support, contact [email protected].

• Privacy Policy
• Terms of Service
• Contact: [email protected]