# FYI Pages MCP - page tools

This is the machine-readable guide for using FYI Pages MCP **page** tools.
Fetch this markdown. Do not scrape the HTML app shell.

- Raw markdown: `/MCP_Pages_svc.md`
- Page JSON file format (if you need a downloadable `.fyi` file): `/fyi-page-instructions.md`

MCP server name: `fyi-pages`  
Endpoint: `https://api.fyinotes.com/mcp/` (trailing slash required)

This document covers only:

- Pages (native FYI JSON)
- Pages (markdown, linked default doc)

It does **not** cover health tools (`fyi_ping`, `get_api_build`) or log tools.

## Connect

1. Sign in and verify your email.
2. Settings → Get MCP Token. One token per verified account.
3. Add the server to your MCP client. Put the token in an environment variable. Do not commit it.

```json
{
  "mcpServers": {
    "fyi-pages": {
      "url": "https://api.fyinotes.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}
```

Restart the client after changing the config.

## Which page tools to use

Prefer **native FYI JSON** tools for real notes. They keep note ids and support headers, text, expandable notes, URLs, JSON, and Mermaid.

Use **markdown** tools only for the linked default page, and only when you want a markdown read or a full rebuild.

| Goal | Tool | Writes? |
|---|---|---|
| Read a page as structured notes | `get_fyi_page` | No |
| Create a new cloud page | `create_fyi_page` | Yes |
| Append notes without rewriting the rest | `add_fyi_notes` | Yes |
| Patch existing notes by id | `update_fyi_notes` | Yes |
| Read the linked default page as markdown | `get_project_page` | No |
| Replace that page from markdown | `update_project_page` | Yes — rebuilds **all** notes |

`update_project_page` destroys existing note ids. Do not use it unless the user wants the whole page rewritten from markdown.

Always pass `updt` from the last read or write. Use `force: true` only to ignore a newer cloud page.

Omit `doc_id` and `skey` to use the linked default page. Pass both to target another page you already own.

Keep page content safe: no scripts, event handlers, iframes, forms, or invented URLs. Do not put passwords or secrets on a page.

---

## Pages (native FYI JSON)

### Note object

Used by `create_fyi_page`, `add_fyi_notes`, and `update_fyi_notes` (plus `id` on update).

| Field | Meaning |
|---|---|
| `title` | Visible title (`t0`) |
| `body` | Blob body for types `2` / `3` / `11` / `12` |
| `ty` | `"1"` text, `"2"` expandable, `"3"` large, `"4"` URL, `"5"` rule, `"7"` header, `"11"` JSON, `"12"` Mermaid |
| `url` | Required for type `"4"` |
| `pre2` | Symbol 0–9 |
| `col` | Column 1–12 |
| `id` | Required for `update_fyi_notes` |

### `create_fyi_page`

Create a new cloud page. Returns `id`, `skey`, and `updt`. Keep those values.

| Name | Type | Default | Description |
|---|---|---|---|
| `title` | string | required | Page title |
| `agent_id` | string | `"default"` | Agent label stored as `source` |
| `notes` | list | `[]` | Optional initial notes |
| `doc_id` | int | `0` | Optional unused page id |
| `skey` | string | `""` | Optional unused skey |

```text
Use fyi-pages: create_fyi_page
  title: "MCP test page"
  agent_id: "default"
  notes: [
    {"title": "Planning", "ty": "7"},
    {"title": "First task", "body": "Write the outcome in one sentence.", "ty": "2"}
  ]
```

### `get_fyi_page`

Read a page as structured notes. Use returned note `id` values with `update_fyi_notes`. Pass returned `updt` on writes.

| Name | Type | Default | Description |
|---|---|---|---|
| `agent_id` | string | `"default"` | Agent label |
| `doc_id` | int | `0` | Page id. With `skey`, selects that page |
| `skey` | string | `""` | Page skey. Required if `doc_id` is set |

```text
Use fyi-pages: get_fyi_page
  agent_id: "default"
  doc_id: <id>
  skey: "<skey>"
```

Success includes `id`, `skey`, `title`, `updt`, `noteCount`, and `notes` (`id`, `ty`, `t0`, `body`, `url`, `col`, `pre2`, `ordr`).

### `add_fyi_notes`

Append notes without rewriting other notes. `ordr` continues from the current max, spaced by 100. New note ids are minted.

| Name | Type | Default | Description |
|---|---|---|---|
| `notes` | list | required | Note objects |
| `agent_id` | string | `"default"` | Agent label |
| `doc_id` | int | `0` | Page id |
| `skey` | string | `""` | Page skey |
| `updt` | int | `0` | Last-seen page `updt` |
| `force` | bool | `false` | Skip last-seen `updt` check |

```text
Use fyi-pages: add_fyi_notes
  agent_id: "default"
  doc_id: <id>
  skey: "<skey>"
  updt: <updt from last read or write>
  notes: [{"title": "Follow-up"}]
```

### `update_fyi_notes`

Patch existing notes by note `id`. Shared fields stay in sync on `d` and `b`. Body for types `2` / `3` / `11` / `12` stays on the blob.

| Name | Type | Default | Description |
|---|---|---|---|
| `notes` | list | required | Objects with required `id` plus fields to change |
| `agent_id` | string | `"default"` | Agent label |
| `doc_id` | int | `0` | Page id |
| `skey` | string | `""` | Page skey |
| `updt` | int | `0` | Last-seen page `updt` |
| `force` | bool | `false` | Skip last-seen `updt` check |

Unknown note ids return `not_found`.

```text
Use fyi-pages: update_fyi_notes
  agent_id: "default"
  doc_id: <id>
  skey: "<skey>"
  updt: <updt>
  notes: [{"id": <note id>, "title": "Renamed"}]
```

Typical flow: `create_fyi_page` → keep `id` / `skey` / `updt` → `get_fyi_page` / `add_fyi_notes` → `update_fyi_notes`.

---

## Pages (markdown, linked default doc)

These tools always use the linked default page for the MCP owner. They do not take `doc_id` / `skey`.

Markdown support is limited: headings (`#`), bullet lists (`-`, `*`), checkboxes (`- [ ]`, `- [x]`), and long lines split into body notes.

### `get_project_page`

Read the linked page as markdown text.

| Name | Type | Default | Description |
|---|---|---|---|
| `agent_id` | string | `"default"` | Agent label |

```text
Use fyi-pages: get_project_page
  agent_id: "default"
```

Success includes `id`, `skey`, `title`, `updt`, and `content` (markdown). Use that `updt` on `update_project_page`.

### `update_project_page`

Write markdown/text to the linked page. This **rebuilds all notes** and replaces note ids.

| Name | Type | Default | Description |
|---|---|---|---|
| `agent_id` | string | required | Agent label |
| `content` | string | required | Markdown/text body |
| `updt` | int | `0` | Last known `updt` from `get_project_page` |
| `force` | bool | `false` | Overwrite even if the cloud page is newer |
| `title` | string | `""` | Optional page title |

```text
Use fyi-pages: update_project_page
  agent_id: "default"
  updt: <updt from get_project_page>
  content: "# Heading\n- item one"
```

Limits: about 200 KB content, max 500 notes per sync.

Prefer native tools unless the user explicitly wants a full markdown rewrite.