# FYI Pages public connector (OAuth MCP)

Spec version: 1.2 · Last updated: 2026-11-14

This is the machine-readable guide for the **public FYI connector**: an MCP server that any MCP client can add by URL. You sign in with your FYI account in the browser. There is no token to paste.
Fetch this markdown. Do not scrape the HTML app shell.

- Raw markdown: `/MCP_api_svc.md`
- Token-based page tools (`api.fyinotes.com/mcp/`): `/MCP_Pages_svc.md`
- Page JSON file format (if you need a downloadable `.fyi` file): `/fyi-page-instructions.md`

MCP server name: `fyi-pages-public`  
Endpoint: `https://mcp.fyinotes.com/mcp` (no trailing slash)  
Transport: streamable HTTP  
Auth: OAuth 2.1 authorization code + PKCE (`S256`), with dynamic client registration

This document covers:

- Signing in and adding the connector to Claude, ChatGPT, Cursor and VS Code
- Scopes, limits, and how to disconnect
- The six tools: `fyi_ping`, `list_my_pages`, `get_my_page`, `create_my_page`, `add_my_notes`, `update_my_notes`

## Connect

1. Have an FYI account. Your client needs nothing else, because it registers itself.
2. Add `https://mcp.fyinotes.com/mcp` to your MCP client as a remote (HTTP) server. Use the examples below.
3. When the client says to sign in, it opens your browser. Sign in to FYI if asked. The **Connect an app** page (`/connect-mcp`) shows the app name, where it sends you back, and what it can do. Under **Pages it can use**, tick the cloud pages it may read and edit (a filter helps you find them). Nothing is ticked by default.
4. Choose **Allow**. The browser returns to your app, and the app is connected. **Deny** sends the app an `access_denied` error.

Restart the client after changing a config file.

### OAuth details (for client developers)

| Item | Value |
|---|---|
| Protected resource metadata | `https://mcp.fyinotes.com/.well-known/oauth-protected-resource/mcp` |
| Authorization server metadata | `https://mcp.fyinotes.com/.well-known/oauth-authorization-server` |
| Issuer | `https://mcp.fyinotes.com/` |
| Endpoints | `/authorize`, `/token`, `/register`, `/revoke` on `https://mcp.fyinotes.com` |
| Grant types | `authorization_code`, `refresh_token` |
| PKCE | Required, `S256` only |
| Client registration | RFC 7591 dynamic registration. Public clients only (`token_endpoint_auth_method: "none"`), 1–5 `redirect_uris` |
| Resource (RFC 8707) | `https://mcp.fyinotes.com/mcp`. Any other `resource` is refused |
| Access token lifetime | 1 hour (default) |
| Refresh token lifetime | 30 days (default). Refresh tokens rotate. Reusing an old one revokes the whole sign-in |
| Authorization code lifetime | 5 minutes, single use |
| Consent request lifetime | 10 minutes, single use |

A request to `/mcp` without a valid token returns `401` with `WWW-Authenticate: Bearer resource_metadata="https://mcp.fyinotes.com/.well-known/oauth-protected-resource/mcp"`.

### Allowed redirect URIs

| Redirect URI | Allowed? |
|---|---|
| `https://…` (any host) | Yes |
| `http://` on a loopback host (`127.0.0.1`, `localhost`, `::1`), any port | Yes |
| `http://` on any other host | No |
| A custom app scheme such as `cursor://` | Only if the server operator enables that scheme |

Registration is rejected if **any** of the client's `redirect_uris` is not allowed.

The redirect must match a registered URI exactly, including the port. Clients that pick a new loopback port each time should register again.

### Claude (claude.ai, Claude Desktop, mobile)

Add it as a custom connector: **Settings → Connectors → Add custom connector**. Your plan or workspace may show this under **Customize → Connectors**.

- Name: `FYI Pages`
- Remote MCP server URL: `https://mcp.fyinotes.com/mcp`
- Leave the OAuth client ID and secret empty. Claude registers itself.

Then choose **Connect**. Claude uses `https://claude.ai/api/mcp/auth_callback` (or the `claude.com` equivalent), which is allowed.

### Claude Code

```text
claude mcp add --transport http fyi-pages-public https://mcp.fyinotes.com/mcp
```

Then run `/mcp` in Claude Code and pick `fyi-pages-public` to sign in. Claude Code uses a loopback redirect, which is allowed.

### ChatGPT

On ChatGPT on the web, go to **Plugins → + → Add custom MCP server**:

- Name: `FYI Pages`
- Connection → Server URL: `https://mcp.fyinotes.com/mcp`
- Authentication: OAuth (no client ID or secret)

Accept the warning, choose **Create as a plugin**, and sign in when asked. In a chat, type `@` and pick the plugin. Workspace admins may need to allow custom MCP servers. ChatGPT uses an `https://chatgpt.com/…` redirect, which is allowed.

### Cursor

`~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "fyi-pages-public": {
      "url": "https://mcp.fyinotes.com/mcp"
    }
  }
}
```

Then open Cursor Settings → **Tools & MCP** (called **MCP** in older versions) and choose **Connect** on `fyi-pages-public`.

**Cursor may not connect yet.** When Cursor registers, it sends a `cursor://anysphere.cursor-mcp/oauth/callback` redirect along with its `http://localhost:8787/callback` and `https://www.cursor.com/…` ones. Registration only works when the server has enabled the `cursor` scheme, and as of 2026-11-13 that isn't confirmed. If Cursor shows a registration or `invalid_redirect_uri` error, that is the cause.

### VS Code (and VS Code Insiders)

`.vscode/mcp.json` in the workspace, or **MCP: Open User Configuration**:

```json
{
  "servers": {
    "fyi-pages-public": {
      "type": "http",
      "url": "https://mcp.fyinotes.com/mcp"
    }
  }
}
```

Start the server from the editor (or **MCP: List Servers → fyi-pages-public → Start Server**) and allow the sign-in. VS Code registers `https://vscode.dev/redirect`, `https://insiders.vscode.dev/redirect`, `http://127.0.0.1/` and `http://127.0.0.1:33418/`, all of which are allowed. No `vscode://` scheme is needed.

## Scopes and access

| Scope | Lets the app |
|---|---|
| `pages:read` | Use `list_my_pages` and `get_my_page` |
| `pages:write` | Also use `create_my_page`, `add_my_notes` and `update_my_notes` |

- With no `scope`, a client gets both scopes. Any other scope is refused with `invalid_scope`.
- A write tool on a read-only connection returns `forbidden` ("This connection can only read pages").
- **Only pages you own.** Tools take a `doc_id` only. They never take or return a page `skey`. Pages shared with you as a collaborator can't be reached. A page that is missing and a page owned by someone else give the same `not_found` answer.
- **Only pages you allow.** A connected app starts with **no** access to your existing pages. See [Page access](#page-access) below.

## Page access

Like the token server, where a page was reachable only if you handed out its key, a connected app only reaches the pages you allow:

- **When you connect:** the consent page (`/connect-mcp`) lists your **cloud** pages, newest first, with a filter. Nothing is ticked by default. Tick the ones the app may use. Allowing none is fine: the app can still create pages.
- **New pages:** with `pages:write`, an app can always create pages. Every page it creates is allowed automatically, so it can read and edit it right away.
- **Per page:** on a cloud page, open **Page Settings** and use the **Allow AI connectors** switch (under **Collab with AI**). It turns that page on or off for every connected app. A page saved only in your browser shows a greyed-out switch and a hint to sync it to the cloud first.
- **All pages:** open **Settings → AI connector access** (or `/connect-mcp` directly). The list shows all your cloud pages, each with a switch. Changes apply at once to every app you connected, with no need to reconnect.
- **Only cloud pages** appear in the picker and the access list. Sync a browser-only page to the cloud first if you want to allow it.
- Access is per account and page: a page you allow can be used by all the apps you connected with that account.
- A connected app can't delete pages. A page you haven't allowed answers `not_found`, the same as a missing page, and `list_my_pages` doesn't show it.
- Every tool call is audited (account, app, tool, page id, result, time, IP). Tokens, codes and page keys are never logged.

## Disconnect (revoke)

- **From the app:** remove or disconnect the connector in your client. Clients that support OAuth revocation call `/revoke`, which ends that sign-in and its refresh tokens.
- **There is no FYI settings page yet** to list or revoke connected apps. To cut an app off from your pages, turn them off in **AI connector access** (`/connect-mcp`); this applies to every connected app. If an app doesn't revoke on disconnect, its access token still works for up to 1 hour, and its refresh token for up to 30 days unless it's used again.
- Each new sign-in is separate. Allowing an app again doesn't revoke the earlier one.

## Limits

| Limit | Value | Applies to |
|---|---|---|
| Tool calls | 60 per minute | Per FYI account |
| Tool calls | 2,000 per day | Per FYI account |
| Write tool calls | 20 per minute | Per FYI account (`create_my_page`, `add_my_notes`, `update_my_notes`) |
| `POST /register` | 20 per hour | Per IP |
| `POST /oauth/approve` (Allow/Deny) | 30 per 10 minutes | Per IP |
| `POST /token` | 60 per minute | Per IP |
| Page size | 200 KB of note data | Per page |
| Notes | 500 | Per page |
| `list_my_pages` | 1–200 pages | Per call |

- An over-limit tool call returns `{"ok": false, "code": "rate_limited", "error": "Too many requests. Try again later.", "retry_after": <seconds>}`.
- An over-limit OAuth endpoint returns HTTP `429` `{"error": "slow_down"}` with a `Retry-After` header.

## Results and errors

- Success is `{"ok": true, ...}`.
- Errors are `{"ok": false, "code": "...", "error": "..."}`, plus safe details where noted.

| `code` | When | Extra fields |
|---|---|---|
| `unauthorized` | Sign-in no longer valid | |
| `forbidden` | Write tool on a `pages:read` connection, or no access | |
| `rate_limited` | See Limits | `retry_after` |
| `invalid` | Bad input (message says what) | |
| `not_found` | Page not yours, not allowed for the connector, or missing; unknown note `id` on update | `noteId` |
| `conflict` | `updt` missing or stale | `dbUpdt`, `incomingUpdt` |
| `too_large` | Over 200 KB or 500 notes | `maxBytes`, `bytes` (size only) |
| other (`unavailable`, `sync_failed`, `error`) | Server problem; retry later | message is `Request failed` |

## Which tool to use

| Goal | Tool | Scope | Writes? |
|---|---|---|---|
| Check the connector is reachable | `fyi_ping` | any | No |
| Find your pages and their `doc_id` | `list_my_pages` | `pages:read` | No |
| Read a page as notes, CSV or Markdown | `get_my_page` | `pages:read` | No |
| Create a new cloud page | `create_my_page` | `pages:write` | Yes |
| Append notes (or change layout) | `add_my_notes` | `pages:write` | Yes |
| Patch existing notes by `id` | `update_my_notes` | `pages:write` | Yes |

There is no tool that deletes pages or notes, and no markdown full-rewrite tool. The markdown rewrite exists only on the token server (`/MCP_Pages_svc.md`).

Keep page content safe. Text containing `<script`, `javascript:`, `<iframe`, `<form`, `onerror=` or `onload=` is rejected with `invalid`. Do not put passwords or secrets on a page.

---

## Pages

### `updt` and `force`

Every page has an `updt` value (milliseconds). Reads and writes return it.

- Writes (`add_my_notes`, `update_my_notes`) must pass the `updt` from your **last read or write** of that page.
- If `updt` is missing or `0`, the write fails with `conflict` ("updt from the last read is required unless force=true").
- If the page changed since, the write fails with `conflict` ("Cloud document is newer or equal"), with `dbUpdt` (current) and `incomingUpdt` (yours). Read the page again, then retry with the new `updt`.
- `force: true` skips the check and writes over newer changes. Use it only when the user wants that.
- Each successful write returns the new `updt`. Use it for the next write.

### Columns and Semantic table

The six-character page flag `meta_ty` sets the layout:

- **Columns** (default `"000000"`): notes stack independently in each `col`.
- **Semantic table** (`"010000"`): notes use `col` plus `row` to form an aligned grid. Notes with the same `row` sit on one line. If `row` is missing, FYI uses `floor(ordr / 100)`.

`meta_ty` must be exactly six `0`/`1` characters. `col_count` (the number of page columns) is clamped to 1–12.

### Note object

Used by `create_my_page`, `add_my_notes` and `update_my_notes` (plus `id` on update). `notes` is a list of objects. A single object, or a JSON string of either, is also accepted.

| Field | Type | Meaning |
|---|---|---|
| `title` | string | Visible title (`t0`), max 800 chars |
| `body` | string | Body text, max 5000 chars. Stored for types `2` / `3` / `11` / `12`. Type `11` needs valid JSON |
| `ty` | string | `"1"` text, `"2"` expandable, `"3"` large, `"4"` URL, `"5"` rule, `"7"` header, `"11"` JSON, `"12"` Mermaid |
| `url` | string | Link (`t1`), max 2000 chars. Required for type `"4"` |
| `phone` | string | `t2`, max 80 chars |
| `address` | string | `t3`, max 400 chars |
| `email` | string | `t4`, max 320 chars |
| `pre2` | int | Symbol 0–9. Default `2`, or `0` for types `5` and `7` |
| `col` | int | Column 1–12 (out-of-range values are clamped). Default `1` |
| `row` | int | Positive integer, for Semantic table pages |
| `ordr` | int | Positive sort order. On append, it defaults to the current max + 100 per note |
| `id` | int | Note id. Required for `update_my_notes`, ignored on create/append |

If `ty` is omitted on create/append: with `body` it becomes `"2"`, with only `url` it becomes `"4"`, and otherwise `"1"`.

On update:
- Adding a `body` to a type `"1"` or `"4"` note turns it into type `"2"`.
- Adding a `url` to a plain type `"1"` note that has no body turns it into a link note (`"4"`).

---

### `fyi_ping`

Check that the connector is reachable. No parameters. Returns the string `pong`. Not rate-limited or audited.

```text
Use fyi-pages-public: fyi_ping
```

### `list_my_pages`

List the cloud pages you allowed for the connector (picked on the consent page or in AI connector access, plus pages the connector created), newest `updt` first. Your other pages are not listed.

| Name | Type | Default | Description |
|---|---|---|---|
| `limit` | int | `50` | Pages to return, clamped to 1–200 |

```text
Use fyi-pages-public: list_my_pages
  limit: 20
```

Success: `{"ok": true, "pages": [{"doc_id": 1763000000000, "title": "Trip plan", "updt": 1763000000123}, ...]}`

### `get_my_page`

Read one of your allowed pages. A page you haven't allowed answers `not_found`.

| Name | Type | Default | Description |
|---|---|---|---|
| `doc_id` | int | required | Page id (positive integer) |
| `format` | string | `"json"` | `"json"`, `"csv"` or `"markdown"` |

```text
Use fyi-pages-public: get_my_page
  doc_id: <doc_id>
  format: "json"
```

Success includes:
- `id`, `title`, `cat`, `meta_ty`, `col_count`, `updt`, `noteCount`, `format`;
- with `json`, `notes`, each with `id`, `ty`, `t0`, `body`, `url`, `phone`, `address`, `email`, `col`, `row`, `pre2`, `ordr`, `updt`;
- with `csv` or `markdown`, the text in `content` instead of `notes`.

Use the note `id` values with `update_my_notes`, and the page `updt` on your next write.

### `create_my_page`

Create a new cloud page that you own. The page id is generated by the server. The new page is allowed for your connected apps automatically. Returns `id`, `updt` and `granted` (`true` when the page was allowed; `false` only if page access couldn't be saved). Keep `id` and `updt`.

| Name | Type | Default | Description |
|---|---|---|---|
| `title` | string | required | Page title (max 160 chars; empty becomes `FYI Page`) |
| `notes` | list | `null` | Optional initial note objects |
| `meta_ty` | string | `"000000"` | Layout flag. `"010000"` makes a Semantic table |
| `col_count` | int | `3` | Page columns, 1–12 |

```text
Use fyi-pages-public: create_my_page
  title: "Weekly plan"
  notes: [
    {"title": "Planning", "ty": "7"},
    {"title": "First task", "body": "Write the outcome in one sentence."},
    {"title": "Docs", "url": "https://fyinotes.com/MCP_api_svc.md"}
  ]
```

Success: `id`, `title`, `updt`, `noteCount`, `cat`, `bytes`, `addedNoteIds`, `granted`.

### `add_my_notes`

Append notes to one of your allowed pages without rewriting the others. New note ids are minted. You can also change the page layout in the same call.

| Name | Type | Default | Description |
|---|---|---|---|
| `doc_id` | int | required | Page id |
| `notes` | list | required | Note objects (may be `[]` if you only change `meta_ty` / `col_count`) |
| `updt` | int | `0` | `updt` from your last read or write. Required unless `force` |
| `force` | bool | `false` | Skip the `updt` check |
| `meta_ty` | string | `""` | Optional new layout flag (empty = unchanged) |
| `col_count` | int | `0` | Optional new column count (0 = unchanged) |

```text
Use fyi-pages-public: add_my_notes
  doc_id: <doc_id>
  updt: <updt from last read or write>
  notes: [{"title": "Follow-up", "pre2": 3}]
```

Success: `id`, `title`, `updt`, `noteCount`, `cat`, `bytes`, `addedNoteIds`, `granted`.

### `update_my_notes`

Patch existing notes by note `id` on one of your allowed pages. Only the fields you send change.

| Name | Type | Default | Description |
|---|---|---|---|
| `doc_id` | int | required | Page id |
| `notes` | list | required | Objects with a required `id` plus the fields to change |
| `updt` | int | `0` | `updt` from your last read or write. Required unless `force` |
| `force` | bool | `false` | Skip the `updt` check |

An unknown note `id` returns `not_found` with `noteId`. Nothing is saved.

```text
Use fyi-pages-public: update_my_notes
  doc_id: <doc_id>
  updt: <updt>
  notes: [{"id": <note id>, "title": "Renamed", "pre2": 4}]
```

Success: `id`, `title`, `updt`, `noteCount`, `cat`, `bytes`, `updatedNoteIds`.

Typical flow: `list_my_pages` → `get_my_page` (keep `updt` and note ids) → `add_my_notes` / `update_my_notes` (pass `updt`, keep the new one).

---

## Compared with the token server

| | Public connector (this doc) | Token server |
|---|---|---|
| Endpoint | `https://mcp.fyinotes.com/mcp` | `https://api.fyinotes.com/mcp/` (trailing slash) |
| Sign-in | OAuth in the browser, nothing to paste | Settings → Get MCP Token, sent as `Authorization: Bearer` |
| Pages | Only pages you own **and allow** (plus pages it creates), by `doc_id`. Cloud pages only; no delete | Linked default page, or another page you own by `doc_id` + `skey` |
| Tools | `list_my_pages`, `get_my_page`, `create_my_page`, `add_my_notes`, `update_my_notes`, `fyi_ping` | `get_fyi_page`, `create_fyi_page`, `add_fyi_notes`, `update_fyi_notes`, `get_project_page`, `update_project_page`, plus health tools |
| Scopes | `pages:read` / `pages:write` | Full access for the token owner |
| Docs | `/MCP_api_svc.md` | `/MCP_Pages_svc.md` |

Both write the same native page format. See `/fyi-page-instructions.md` for the full `.fyi` page model.
