Install the Tiro MCP server in this workspace.
Server URL : https://mcp.tiro.ooo/mcp
Transport : HTTP (streamable)
Auth : OAuth (preferred). On first connection, the user opens
a browser for Google sign-in. Tokens cache locally for
180 days.
IMPORTANT: You (the AI) cannot open a browser or click "Authenticate"
yourself. After install, instruct the user to complete the OAuth step
in their MCP client.
Per-client install commands:
· Claude Code (CLI):
claude mcp add --transport http --scope project tiro \
https://mcp.tiro.ooo/mcp
Then ask the user to run /mcp inside Claude Code and select
"Authenticate" on the "tiro" entry.
· Claude Desktop / Cursor / VS Code:
Edit the MCP config (claude_desktop_config.json, Cursor MCP
settings, .vscode/mcp.json) and add an HTTP entry pointing at
https://mcp.tiro.ooo/mcp. The user signs in via OAuth on first
load.
· stdio-only clients (no HTTP support):
Wrap with mcp-remote:
npx -y mcp-remote https://mcp.tiro.ooo/mcp
If the user cannot run a browser flow (CI / headless / sandbox), ask
them for a Tiro API key from
https://platform.tiro.ooo/dashboard/api-keys and attach the header:
Authorization: Bearer <TIRO_API_KEY>
After install, MCP tools usually only appear after a session restart.
Tell the user to restart, then call `auth_status` to confirm the
session is live and list the Tiro tools that loaded. If any step
fails, show the exact error and the step where it happened — do not
retry silently.
Set up Tiro REST API access in this environment.
Base URL : https://api.tiro.ooo
Auth : Bearer token (API key = id + "." + secret)
Content : application/json
IMPORTANT: You (the AI) cannot create the API key. The user must
generate it themselves and paste it back. Walk them through it.
Steps:
1. Tell the user to open
https://platform.tiro.ooo/dashboard/api-keys, create a new key,
and copy the FULL string — id, dot, and secret together. The
secret is shown only once. Using only the id portion will fail
with 401.
2. When the user pastes the key, store it as an environment
variable. Never hardcode. Pick the right target:
· Project-scoped: write to .env.local (or .env) and add it
to .gitignore.
· Shell-scoped: append to ~/.zshrc (or ~/.bashrc) so it
persists across sessions.
Example:
export TIRO_API_KEY="<paste-id.secret-here>"
3. Test the first call (list notes):
curl https://api.tiro.ooo/v1/external/notes \
-H "Authorization: Bearer $TIRO_API_KEY" \
-H "Content-Type: application/json" \
-w "\n%{http_code}\n"
Expected response: JSON with `content[]` array of notes,
each containing `guid`, title, createdAt, status. Pagination
via `nextCursor`.
If you get 401, check the Bearer string contains the dot separator.
If you get 429, you hit the hourly rate limit — wait before retry.
Show the user the exact error payload — do not retry silently.
Full reference: https://api-docs.tiro.ooo/fundamentals/api-overview
Install the Tiro CLI in this environment and sign me in.
Package : @theplato/tiro-cli (Node.js 20+)
Platforms : macOS, Linux, Windows
Auth : OAuth (Authorization Code + PKCE) — opens a browser
and stores the token in the OS keychain.
Steps:
1. Install globally with whichever package manager is already in
use here. For npm, that is:
npm install -g @theplato/tiro-cli
(Use pnpm / yarn / bun equivalents if those are the active
package manager — do not switch tooling. If no lockfile is
present, default to npm.)
2. Verify the install:
tiro --version # expect 0.3.1 or later
3. Detect environment:
· If `$DISPLAY` is set OR `open`/`xdg-open` is available:
treat as interactive → proceed to OAuth.
· If `$SSH_TTY` is set, or `$CI` is set, or no display open
command exists: treat as headless → skip OAuth.
4. Interactive path — sign in:
tiro auth login # opens a browser for OAuth
tiro auth status # confirm: shows user + token prefix
5. Headless path — ask the user for a token instead:
export TIRO_TOKEN="<paste-token-here>"
The token is generated by visiting the same login URL in a
browser-equipped machine and copying the result.
6. Prove the CLI works:
tiro notes list --limit 3 --json
Show me the output. Exit code 0 = success, 4 = auth required
(go back to step 4 or 5), other = report the JSON error
envelope verbatim.
Set up a Tiro webhook endpoint to receive note events.
Method : POST with application/json body
Auth : Bearer token in Authorization header
Tiro sends: Authorization: Bearer <WEBHOOK_SECRET>
You compare it against your stored secret using a
constant-time compare (e.g. crypto.timingSafeEqual).
Timeout : 60 seconds per delivery
Retries : Up to 5 with exponential backoff over ~2 hours
IMPORTANT: You (the AI) cannot register the endpoint in the dashboard.
The user must do step 1 themselves and paste the secret back.
Steps:
1. Tell the user to register their HTTPS endpoint at
https://platform.tiro.ooo, copy the WEBHOOK_SECRET shown after
registration, and paste it here. Store it as an env var (use
.env.local for project scope; never commit):
export WEBHOOK_SECRET="<paste-here>"
2. Build an HTTP POST handler that:
a. Reads the Authorization header.
b. Strips "Bearer " and constant-time-compares the remainder
to WEBHOOK_SECRET. Return 401 on mismatch.
c. Parses the JSON body into { id, type, createdAt, data }.
d. Routes by `data.resourceType`:
- Note (note.created/updated/deleted)
- NoteSummary (noteSummary.created)
- NoteDocument (noteDocument.created/updated)
- FolderNoteRelation (folderNoteRelation.created/deleted)
e. Tracks event.id in a durable processed-set for idempotency
(Redis / DB in production; in-memory only for local dev).
Retries with the same id are EXPECTED — return 200 with
{ status: "duplicate" } on repeat.
f. Returns 2xx on success, 5xx for transient (will retry),
4xx for permanent (no retry).
3. Pick one language (Node / Python / Go / Kotlin+Spring) the user
is already on, write the receiver code, and show how a
`note.created` event flows end-to-end.
4. Test:
curl -X POST <endpoint> \
-H "Authorization: Bearer $WEBHOOK_SECRET" \
-H "Content-Type: application/json" \
-d '{"id":"evt_test","type":"note.created","createdAt":"2026-05-18T00:00:00Z","data":{"resourceType":"Note","id":"n_1"}}'
Expect 200 within 60 seconds.
Full reference:
Events: https://api-docs.tiro.ooo/webhooks/events/schema
Best practices: https://api-docs.tiro.ooo/webhooks/best-practices
イ・キョンフン
