Miracle developer docs | MCP server and REST API

For Claude, ChatGPT, Cursor, and MCP clients

Connect an AI assistant

Use Miracle's hosted Streamable HTTP server. OAuth keeps your password and API token out of supported client configurations.

https://miracle.fyi/mcp

MCP setup, tools, safety, and troubleshooting →

For scripts, automations, and your own product

Build with the REST API

Call the same account-scoped operations directly with a dedicated bearer token. Start with identity, then read before you write.

https://miracle.fyi/api/v1

Explore the interactive API reference →

REST quickstart

From token to first safe write

The dedicated AI tools token is separate from your private email-to-inbox address. Keep it out of URLs, screenshots, source control, and logs.

1

Get the dedicated token

Open Miracle, choose Settings → AI tools, and copy the API token. Rotate it there at any time without changing your inbox address.
Start free and get access →

Confirm the account and timezone

Every integration should identify the connected account before its first mutation.

export MIRACLE_API_KEY="your_token_here"

curl -sS https://miracle.fyi/api/v1/me \
  -H "Authorization: Bearer $MIRACLE_API_KEY"

3
Read a small page of work

Lists use opaque cursor pagination. Keep the limit modest and pass next_cursor back unchanged when more results exist.
```
curl -sS "https://miracle.fyi/api/v1/todos?section=today&status=active&limit=20" \
  -H "Authorization: Bearer $MIRACLE_API_KEY"
```

Create once, even when the network retries

Use a unique Idempotency-Key for each logical create. Repeating the same key and payload returns the original task. Reusing the key with different content fails safely.

curl -sS https://miracle.fyi/api/v1/todos \
  -X POST \
  -H "Authorization: Bearer $MIRACLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: board-packet-2026-07-14" \
  -d '{
    "text": "Prepare the board packet",
    "section": "priority",
    "checklist": ["Cover memo", "Exhibits", "Final review"]
  }'

Canonical references

One source for each job

These surfaces are deliberately separate so human guidance, interactive exploration, and machine contracts do not drift into competing copies.

MCP guideConnect clients, understand scopes, browse tool groups, and troubleshoot.Human setup API referenceSearch every operation and inspect request and response schemas.Interactive Scalar OpenAPI 3.1Generate clients, validate payloads, or import the complete contract.Machine-readable JSON llms.txtGive an agent the compact operating rules, endpoints, and safety boundary.Assistant-readable text

Reliability contract

Retries should not create surprises

Create operations support idempotency keys.
Lists use stable cursor pagination instead of fragile offsets.
Goal Grid, journal, North Star, and Time on Earth can reject stale writes.
Errors include a stable machine code and a human-readable message.
Rate-limited responses identify when the client should retry.

Financial boundary

Agents cannot move money

MCP and REST cannot create or change financial stakes, payment methods, charges, disputes, refunds, or account billing. Those decisions remain inside the authenticated app.

Read the complete safety boundary →

Distribution

Hosted first. Nothing to install.

The supported public MCP server is the URL above, with OAuth and automatic updates. Miracle does not currently publish an official npm package. Do not install packages that merely look official. If a verified local stdio package is published later, this page and the MCP guide will name and link it directly.

Use the hosted MCP server →

One practice. Every assistant and workflow.