— <url>`) — use it: tell the user WHICH tab you're in when you hand over, since the `view_url` live view opens on exactly this tab. On a shared/many-tab profile the active tab is pinned + self-healing, so background tabs reloading/timing out never swap it; but if the tab you were driving was CLOSED, the shot is a different tab and the result carries a "⚠️ the tab you were driving was closed — this is a DIFFERENT tab" note → `browser_list_tabs`/`browser_switch_tab` to the right one. A "tab busy / timed out" error means the tab's renderer is pinned or still loading — wait ~2-3s and retry, or switch to a responsive tab. - `browser_scroll` — `{ session_id, direction?: 'down'|'up'|'top'|'bottom', amount? }` → scroll the active tab to reveal off-screen content (down/up by ~one viewport or `amount` CSS px; top/bottom jump to the extremes). Returns `{ scroll_y, max_scroll_y, at_bottom }` so you know whether more content remains. Follow with `browser_screenshot`/`browser_get_dom` to see what's now in view. - `browser_click` — `{ session_id, x, y }` → click at CSS-pixel coordinates of the active tab. The click is always DISPATCHED even if the page is mid-operation (e.g. a heavy save it just started). A `page_busy: true` result means the click WAS sent + queued but the page didn't confirm in time — WAIT ~2-3s then `browser_screenshot`/`browser_get_dom` to verify; do NOT assume the page is broken, navigate away, or re-click blindly. A `tab_changed: true` result means the tab you had pinned was CLOSED, so this click landed on a DIFFERENT tab at those coordinates (it may have hit the wrong thing) — `browser_screenshot` to see where you are, then `browser_list_tabs`/`browser_switch_tab` if needed. (`browser_type`/`browser_press_key` behave identically.) - `browser_drag` — `{ session_id, from_x, from_y, to_x, to_y, steps? }` → click-and-drag (press at `from` → move to `to` → release). The path for what a click can't do: dragging a resize handle to resize a panel/column, moving a range slider, reordering a list, or HTML5 drag-and-drop. `steps` (default 12) is how many intermediate move events the motion path uses — raise it for DnD libraries that need a real path. Coordinates are CSS-pixels (same space as `browser_click`); if a viewport/device is emulated they map to that emulated size. - `browser_type` — `{ session_id, text }` → type into the focused element (click the field first). - `browser_select_option` — `{ session_id, selector, label?, value? }` → set a native `<select>` dropdown via the DOM. **USE THIS for `<select>`s instead of clicking** — a native select opens its option list in browser chrome OUTSIDE the screencast, so coordinate-clicks (and even human takeover) can't reach the popup. Match by visible `label` (case-insensitive, exact preferred then contains) or `value`. On a miss it returns the available options so you can retry with an exact label. Find the selector with `browser_get_dom`. - `browser_press_key` — `{ session_id, key, modifiers?, times? }` → press a key the typing tool can't send: `Enter` (submit), `Tab` (next field), `ArrowUp`/`ArrowDown` (move within a focused select), Escape, etc. `modifiers` is a CDP bitmask (Alt=1, Ctrl=2, Meta=4, Shift=8). Focus the target first. - `browser_long_press` — `{ session_id, x, y, duration_ms? }` → press and HOLD at (x,y) then release. For buttons that need a deliberate long-press (hold-to-confirm, touch-and-hold menus) that a normal instant `browser_click` can't trigger. `duration_ms` is the hold time (default 800, 50–10000). The mode auto-selects from the emulated device: a mobile-emulated session (set one with `browser_set_viewport` preset=mobile/tablet) sends a real TOUCH hold so `touchstart`/`touchend` long-press handlers fire; otherwise a mouse hold. Returns `{ ok, duration_ms, mode: 'touch'|'mouse' }`. - `browser_set_viewport` — `{ session_id, preset?: 'desktop'|'xl'|'tablet'|'mobile', width?, height?, device_scale_factor?, mobile?, reset? }` → resize the viewport and optionally emulate a mobile/tablet device (touch + mobile user-agent) so you can see and test a page's responsive layout. Pass a `preset` OR custom `width`+`height` (+ `mobile=true` for touch + mobile UA); `reset=true` returns to native. The setting **sticks** for the session — every later `browser_screenshot`/`browser_click`/`browser_drag`/`browser_get_dom` uses it and coordinates map to the emulated size, so set it once then screenshot. Presets: desktop 1280×800, xl 1600×900, tablet 820×1180 (touch), mobile 390×844 (touch + mobile UA). - `browser_run_actions` — `{ session_id?, steps[], delay_ms? }` → run a SEQUENCE of steps in ONE call (over a single browser connection) instead of many separate click/type round-trips. **This is the efficient way to fill a multi-field form** (or several): read the page once with `browser_get_dom` for selectors, then send all steps. Each step is `{ action, ... }`: `fill {selector,text}` (set an input/textarea by CSS selector — the coordinate-free form-fill primitive; fires input/change so React/Vue/Angular update; reaches same-origin iframes), `click {selector}` (DOM click) or `click {x,y}` (coordinate fallback for canvas/custom widgets), `type {text}` (into the focused element), `press_key {key,modifiers?,times?}`, `select_option {selector,label?|value?}`, `scroll {direction?,amount?}`, `navigate {url}`, `wait {ms}` (explicit pause, e.g. after a navigate), `fill_credentials {label?,...}` (server-side wallet fill — you never see the password), `fill_credential_field {field,label?,selector?}` (targeted single-value fill — one saved username/password into a selector'd or focused field; batch `click`→`fill_credential_field`→`press_key Enter` for a two-step login). A short pause (`delay_ms`, default 250, clamp 0–5000) is inserted after each step; a `wait` step uses its own ms. **Stops at the first failing step** → `{ ok, total, completed, failed_at, results:[{index,action,ok,error?,detail?}] }`, so you see exactly where it stopped and resume from there. Max 50 steps/call; same control-mode gate as the single tools. - `browser_list_tabs` — `{ session_id? }` → list the session's open tabs (pages): each with `{ target_id, url, title, active }`. The `active` tab is the one navigate/click/type/screenshot act on. Use it whenever a click opened a popup/new tab, or you're unsure which tab is focused. - `browser_switch_tab` — `{ session_id?, target_id }` → make a tab the active one (and bring it to front) so subsequent navigate/click/type/screenshot act on it. The choice STICKS for the session until you switch again or the tab closes. `target_id` comes from `browser_list_tabs`. - `browser_new_tab` — `{ session_id?, url? }` → open a new tab (optionally at an http(s) `url`) and make it active. Returns the new tab's `target_id`. Use it to work on a second page without losing the first. - `browser_close_tab` — `{ session_id?, target_id }` → close a tab. Refuses to close the last remaining tab; if you close the active tab the next tool falls back to another open tab. - `browser_fill_credentials` — `{ session_id, label?, username_selector?, password_selector? }` → fill a login form on the session's CURRENT page from the user's saved **password wallet**, server-side. **You never see the password** — it's decrypted and typed into the page by the gateway; you only get back `{ ok, label, domain, filled }`. Use this to get past a login wall: navigate to the login page, call this, then submit (`browser_click` the sign-in button or `browser_press_key Enter`). The matching credential is chosen by the page's domain; pass `label` to disambiguate when several logins exist for one site. **Reaches login forms inside iframes** — including cross-origin auth widgets on the **same root domain** (e.g. Apple Developer's `idmsa.apple.com` form embedded in `developer.apple.com`); a form on a DIFFERENT root domain (cross-domain SSO like `login.microsoftonline.com` inside an Azure portal page) is deliberately NOT filled — hand off to the user via takeover for those. If no saved credential matches, it errors — save one with `browser_save_credentials` (if the user gives you the password) or ask them to add it in the dashboard. - `browser_fill_credential_field` — `{ session_id?, field, label?, selector? }` → the MANUAL, targeted fill: insert ONLY the username, the password, or a freshly generated 2FA code (`field`: `username` | `password` | `totp`) from a saved credential into ONE field — still server-side, you never see the value (returns `{ ok, field, label, domain, filled, target }`). Use this when `browser_fill_credentials` can't locate the field: **multi-step logins where the password is on a SEPARATE page (Apple ID / App Store Connect — email first, password next), custom / shadow-DOM password widgets, or unusual markup.** Target the field EITHER by CSS `selector` OR by omitting it and clicking the field first (`browser_click`) so it's focused. Typical Apple flow: `browser_click` the password box → `browser_fill_credential_field { field:"password", label:"Apple" }` → `browser_press_key Enter`. Same security frame-gate as `browser_fill_credentials` (fills same-root-domain iframes like `idmsa.apple.com`, never an unrelated cross-domain frame). Only a visible input/textarea is written. - `browser_set_cookies` — `{ session_id, cookies, domain?, reload? }` → inject cookies into the session so a page is logged in WITHOUT signing in through the form (the path for sites where importing a session cookie is the only/fastest way in). The cookies are written into Chromium server-side and persist with the session's login profile, so a later session on the same profile resumes signed in. `cookies` is EITHER an array of cookie objects (the Cookie-Editor / EditThisCookie browser-extension export: `{ name, value, domain?, path?, secure?, httpOnly?, sameSite?, expirationDate? }`) OR a raw `"name=value; name2=value2"` header string. `domain` is the target host (required for the raw-header form, fallback for array entries without a domain). Reloads the page by default (`reload=false` to skip). Returns `{ ok, set, skipped, domains, reloaded }` — never the cookie values. **Privacy:** the cookie VALUES travel through YOUR context (like saving a credential, unlike a wallet fill) — only do this when the user explicitly hands you cookies to import; the zero-exposure alternative is for them to paste them in the dashboard (Cloud Browser → live view → "Inject cookies"). - `browser_clear_site_data` — `{ session_id?, origins, clear_cache?, reload? }` → factory-reset the listed origins INSIDE the session's browser: localStorage, sessionStorage, IndexedDB, service workers, caches AND those origins' cookies (plus the shared HTTP cache unless `clear_cache=false`), while every OTHER site's login survives. The repair for a heavy SPA stuck broken across sessions because the saved profile keeps restoring poisoned state — canonical case: the Azure/Entra portal permanently showing "Netzwerkfehler"/"Error displaying your content" because it is pinned to a bundle version its CDN no longer serves. `origins` takes bare hosts or https URLs (max 10). Sign-in usually recovers silently, since the identity provider lives on its own origin (e.g. `login.microsoftonline.com`) which is untouched unless you list it. Navigate the tab to a NEUTRAL page first — clearing mid-auth-redirect corrupts in-flight state — and only clear what the user wants reset: the wipe becomes permanent for the profile at the next snapshot. Reloads the active tab by default (`reload=false` to skip). Returns `{ ok, origins, skipped, cache_cleared, reloaded }` — never a stored value. - `browser_inspect_storage` — `{ session_id?, profile_id?, domain?, tokens_only?, reveal? }` → debug a login problem ("the site keeps signing me out", "why is the 2FA prompt back?", "which account is this tab signed in as?") by reading what the browser actually holds: the FULL cookie jar incl. httpOnly cookies, localStorage + sessionStorage per origin, IndexedDB database names — and every token in those values. JWTs are DECODED (issuer, subject, audience, scopes, client id, issued/expires, remaining lifetime, all claims); opaque session/auth tokens are flagged with their expiry and where it came from (`expiry_source`: `jwt` | `json` | `cookie`). For a live session each entry also carries `profile` = `same` | `changed` (a rotating token) | `not_saved` (set after the last snapshot — the next ~2-min checkpoint or releasing the session saves it), plus `saved_only` (saved but gone from the live browser: deleted by the site, expired, or failed to restore). **Read `notes` first** — it states the findings in plain language and names the login-related items. **Redacted by default**: you get lengths, a fingerprint (same value → same fingerprint, so compare two calls to see a token rotate) and decoded claims (the decoded view never carries a JWT signature) — no raw cookie or token value. **`reveal: true`** (boolean or `"true"`) adds the RAW values — cookie values, storage values and each full token, a JWT's signature included — for the caller's own sessions and profiles only. Use it only when the task needs the actual value (the user asks for it, or a cookie/token has to be handed over); a session cookie or token IS the login, so never paste a revealed value anywhere the user didn't ask for. Revealed values are capped at 64,000 characters per call (`BROWSER_INSPECT_AGENT_MAX_REVEAL_CHARS`), spent tokens first (expired / soonest-expiring first), then login (`auth`) cookies and storage keys, then the rest; an entry past the cap keeps its length, fingerprint and claims and is marked `value_omitted: true`, and `notes` says how many were left out — combine reveal with a narrow `domain`. A revealed answer's first note is a warning; every reveal is audit-logged server-side (who, which session/profile, `actor=agent` — never a value). The dashboard "Storage & tokens" panel (the response's `view_url`) shows every value uncapped and keeps it out of the conversation. Pass `domain` (e.g. `"netsuite.com"`) — strongly recommended, a real jar has hundreds of cookies; `tokens_only=true` returns just summary + tokens + diff + notes (the lightest call). Pass `profile_id` instead to inspect a SAVED profile: what the next session on it will start with (no session needed). Read-only and not blocked by the control mode; with a native dialog open only cookies are read. - `browser_upload_file` — `{ session_id?, selector, file_name?, bucket?, object_key?, source_url?, content_base64? }` → put a file into an `<input type=file>` (or a dropzone that owns one) on the active tab — the ONLY way to upload a cert/key/logo/CSV/screenshot (coordinate clicks + typing can't fill a file input). Bytes come from exactly ONE source: a Lynk bucket object (`bucket`+`object_key`), a `source_url` (server-fetched, SSRF-guarded, no redirects), or inline `content_base64`. Point `selector` at the file input OR the visible dropzone (the hidden input inside/associated with it is found automatically). Chromium fires the input's real `input`/`change` events so React/Vue dropzones register the selection. Max 10 MB. Returns `{ ok, used_selector, file_name, size }`. - `browser_download_file` — `{ session_id?, selector? | x+y | url, bucket?, object_key?, share?, timeout_ms? }` → trigger a download on the active tab and store it in the user's Lynk storage (then read it with `bucket_get_object`, hand the user the `/dl/` link, or re-feed it into `browser_upload_file` on another portal). The path for anything that only comes as a browser download behind a login — a purchased asset pack, a generated key/cert (`.p8`/`.p12`), an exported report/CSV, an invoice PDF. TRIGGER = a `selector` click, an `x`+`y` coordinate click, or a direct `url` (session cookies apply). DESTINATION = `bucket` (created if new; `object_key` defaults to the site's filename) and/or `share=true` for a public `https://lynk.run/dl/…` link; omit `bucket` to store it only as a shared file. Streamed to disk (never buffered): max 250 MB by default (operator env `BROWSER_DOWNLOAD_MAX_BYTES`, hard ceiling 1 GB); bucket objects over 10 MB count against a 2 GB total bucket-storage cap, shared files against the shared-file quota. Waits 120 s by default (`timeout_ms` 5000–240000); an oversized download is canceled as soon as the browser reports its size. If the client times out, the file still lands — check `bucket_list_objects` / `files_list` before retrying. Returns `{ ok, bucket?, object_key?, file_name, size, download_url?, share_error? }`. - `browser_fill_totp` — `{ session_id?, label?, selector? }` → type the CURRENT 2FA (authenticator/TOTP) code for a saved login into the one-time-code field on the session's current page. **You never see the code** — it's generated from the stored seed and typed server-side; you get back `{ ok, label, domain, mode, boxes, expires_in_ms }`. Use it when a login lands on "enter your 6-digit code" and `browser_list_credentials` shows `has_totp: true` for that site. It finds the field itself (an `autocomplete="one-time-code"` input, a code-ish named input, or a row of single-character boxes, which it fills with per-digit keystrokes so the widget's auto-advance runs); pass `selector` only if that misses. **A code lasts ~30s — submit immediately**, ideally in the same call: `browser_run_actions` with `[{action:"fill_totp"},{action:"press_key",key:"Enter"}]`. If under 3s of validity remain the server waits for the next code first, so the call can take a moment. No seed saved → it says so; the user can add one in the dashboard, or you can enroll it with `browser_scan_totp_qr`. - `browser_scan_totp_qr` — `{ session_id?, label? }` → read the authenticator QR shown on the session's current page and store its secret on a saved wallet entry, so future logins can be finished with `browser_fill_totp`. This is how you turn 2FA ON autonomously: sign in → open the site's security/2FA settings → start "add authenticator app" → make sure the QR is VISIBLE → call this → confirm the site's verification step with `browser_fill_totp`. **Prefer this over reading the "can't scan the QR?" secret as text** — the QR is decoded from a screenshot inside the gateway, so the seed never passes through your context. Replaces an existing seed if the entry already had one (`replaced: true`) — only do that for a deliberate re-enrollment. Returns `{ ok, label, domain, issuer, account, replaced }`, never the secret. Afterwards tell the user to open Cloud Browser → Passwords and add the account to their phone from the QR shown there. - `browser_save_credentials` — `{ label, domain, username?, password, totp? }` → save a login to the wallet for later filling. Stored encrypted at rest. **Privacy:** saving here passes the password through YOUR context (unlike filling) — only do it when the user explicitly gives you the password to store, CONFIRM the values first, and tell them the dashboard (Cloud Browser → Passwords) is the zero-exposure alternative. Optional `totp` stores a 2FA seed (an `otpauth://` URI or bare base32 secret) — same privacy note, and `browser_scan_totp_qr` is the zero-exposure way to enroll one. Returns the entry without the password. - `browser_list_credentials` — `{}` → labels + sites + usernames of saved logins (NEVER passwords). Use to find a `label` for fill/delete. - `browser_delete_credentials` — `{ label }` → remove a saved login by its wallet label (or id). Confirm with the user first. - `browser_release_session` — `{ session_id }` → stop the session; the login profile (if any) is snapshotted encrypted for a later resume. **Control modes** (`control_mode`, user-switchable live in the dashboard): `agent` (you drive), `hybrid` (you + human share — write tools are refused if a human acted since your last observation; call `browser_screenshot`/`browser_get_dom` to re-check), `human` (human drives — your write tools are refused; reads still work). **Rules:** (1) NEVER click destructive/irreversible actions (delete, pay, revoke, submit) autonomously — navigate there, then ask the user to take over (send them the session's `view_url`) and confirm. (2) For logins, prefer `browser_fill_credentials` (fills a saved login server-side — you never see the password), then submit; if there's no saved credential, either save one with `browser_save_credentials` (only if the user gives you the password — confirm first; it then passes through your context, so mention the dashboard as the zero-exposure path) or hand off to the human via takeover (send the `view_url`). Never type a raw password directly into the page. For a 2FA step: if the wallet entry has a seed (`has_totp`), use `browser_fill_totp`; otherwise read an emailed code from the user's connected Gmail/mailbox and type it, or hand off. Push-approval MFA and hardware keys always need a hand-off. **There is no tool that reveals a stored 2FA seed** — that is dashboard-only, by design. If a login keeps getting lost between sessions, call `browser_inspect_storage` with the site's `domain` (and `tokens_only=true`) before guessing — it shows which login cookies are expired, not saved yet, or gone from the profile. Diagnosing needs no raw value; pass `reveal: true` only when the user needs the actual value (e.g. a cookie to hand to a script). (3) Tabs/popups (OAuth/consent windows) open inside the same session and the live view follows them automatically. **You and the human share ONE active tab**: the live view opens on the tab you're driving (so `view_url` is a true hand-over — say which tab it is), and if the human switches tabs during a takeover, that becomes YOUR active tab too — so after any takeover, `browser_screenshot`/`browser_list_tabs` before acting. (4) Release sessions when done. All sessions/profiles are personal (scoped to you). ### WordPress tools (`wordpress` scope) Content management for connected WordPress sites via the WordPress REST API (Application Passwords). Workspace-scoped — every site is reachable across the user's Lynk workspaces. Read + write. - `wordpress_list_instances` — `{}` → every connected site (`id`, `name`, `base_url`, `last_test_ok`, `instance_context`, `instance_dont`). **Call first** for the `instance_id`; read `instance_context` (site facts) + `instance_dont` (guardrails) before publishing/editing. - `wordpress_update_instance_config` — `{ instance_id, instance_context?, instance_dont? }` → persist per-site AI facts/guardrails (any workspace member). "" / null clears; does NOT touch WordPress content. - `wordpress_list_posts` — `{ instance_id, status?, search?, per_page?, page? }` → `{ total, total_pages, posts[] }` (id, status, slug, link, date, title). `status` ∈ draft/publish/pending/future/private. - `wordpress_get_post` — `{ instance_id, post_id }` → full post incl. raw + rendered title/content/excerpt. - `wordpress_list_pages` — `{ instance_id, status?, search?, per_page?, page? }` → static pages, same shape as posts. - `wordpress_get_page` — `{ instance_id, page_id }` → full page incl. raw + rendered content. - `wordpress_create_post` — `{ instance_id, title, content (HTML), status?, slug?, excerpt?, categories?, tags?, featured_media?, date? }` → created post. **Defaults to `status:"draft"`.** - `wordpress_update_post` — `{ instance_id, post_id, …same fields }` → edit in place (id + URL preserved); every field is "omit = keep". - `wordpress_create_page` — `{ instance_id, title, content (HTML), status?, slug? }` → created static page. **Defaults to `status:"draft"`.** - `wordpress_update_page` — `{ instance_id, page_id, title?, content?, status?, slug? }` → edit a site page in place. This is the tool for changing homepage / landing / product page content. `content` replaces the whole body. - `wordpress_upload_media` — `{ instance_id, filename, mime_type, content_base64 }` → `{ id, source_url, … }`. Use the `id` as `featured_media`, or embed `source_url` in HTML. **Rules:** (1) `content` is HTML — Gutenberg block markup is HTML with `` comments; write it directly. (2) **NEVER publish or delete without explicit user confirmation** — create leaves content as a draft; only set `status:"publish"` after the user says go live, and overwriting an already-published page changes the live site immediately. (3) Schedule with `status:"future"` + a future ISO `date`. (4) Cite the response `link` (the permalink). (5) **Page-builder sites**: if the site uses WPBakery / Visual Composer, `content.raw` is shortcode markup (`[vc_row][vc_column][vc_column_text]…`) — `wordpress_get_page` first, edit the text INSIDE the shortcode blocks, send the full body back, keep the shortcode skeleton intact. Elementor / Divi store layout in postmeta (not the `content` field) — those page bodies are NOT editable via this API. (6) **WPML/multilingual**: each language is a separate page/post id; editing one does not touch the others. ### NetBox tools (`netbox` scope) Read-only access to connected **NetBox** instances — the DCIM/IPAM source of truth for a network. Workspace-scoped: every instance in any of the user's Lynk workspaces is reachable. The NetBox API token is stored AES-256-GCM encrypted; the underlying client accepts only `GET`/`OPTIONS`, so **this scope has no write path at all**. `instance_id` is OPTIONAL on every tool — omit it when the user has exactly one NetBox connection; with several, the error lists the choices. - `netbox_list_instances` — `{}` → every connected instance (`id`, `name`, `base_url`, `netbox_version`, `last_test_ok`, `instance_context`, `instance_dont`). **Call first.** Read `instance_context` (naming conventions, what each tenant/role means) + `instance_dont` before answering. - `netbox_update_instance_config` — `{ instance_id?, instance_context?, instance_dont? }` → persist per-instance AI facts/guardrails (any workspace member). "" / null clears. Does NOT touch NetBox. - `netbox_search` — `{ instance_id?, q, limit? }` → global search across every object type. **The right first step when you know a name but not what kind of object it is** — a hostname could be a device, a VM, an IP address or a DNS name. Each hit names the matching object type (`object_type`) and carries the projected object. On NetBox 4.1+ this uses the server's own `/api/search/`; on older versions (verified against 4.0.2, where that endpoint 404s) it transparently falls back to a parallel `?q=` fan-out across the common models and the response says which path ran (`via: "search_api" | "fanout"`). Fan-out `count` is the aggregate across the searched models. - `netbox_query` — `{ instance_id?, app, model, filters?, limit?, offset?, detail? }` → the workhorse. `app` ∈ `dcim`, `ipam`, `virtualization`, `circuits`, `tenancy`, `wireless`, `vpn`, `extras`, plus the plugin app `inventory`. Common models: `dcim/devices`, `dcim/sites`, `dcim/racks`, `dcim/interfaces`, `dcim/cables`, `ipam/ip-addresses`, `ipam/prefixes`, `ipam/vlans`, `virtualization/virtual-machines`, `circuits/circuits`, `tenancy/tenants`. `filters` are NetBox's own query params, e.g. `{"site":"ffm14","status":"active"}` or `{"q":"ldap"}`. **Asset management** (`app: "inventory"`, the netbox-inventory plugin — 404s if it is not installed): `inventory/assets` (serial, asset tag, warranty dates, who owns it, where it is stored), `inventory/suppliers`, `inventory/purchases`, `inventory/deliveries`, `inventory/inventory-item-types`. **Who supplied a thing depends on what kind of thing it is** — a CIRCUIT has a `provider` (`circuits/providers`), HARDWARE has a `supplier` (`inventory/suppliers`), and a FACILITY has neither in core NetBox. The two lists are different companies and do not overlap; do not answer a hardware question from the provider list or vice versa. - `netbox_get` — `{ instance_id?, app, model, id, detail? }` → one object, full record by default. - `netbox_schema` — `{ instance_id?, app, model }` → field names, types, choices and valid filters from the API's own `OPTIONS` response. **Call this instead of guessing filter names or enum values.** - `netbox_changelog` — `{ instance_id?, since?, filters?, limit?, offset? }` → NetBox's object change log (who changed what, when). Use for "what changed since yesterday", tracing when a record was last touched, or correlating an incident with a documentation change. Filters: `{"action":"delete"}`, `{"changed_object_type":"dcim.device"}`, `{"user_name":"…"}`. The per-row before/after snapshots are stripped to keep a page readable — use `netbox_get` for detail. **Rules:** (1) **Read-only** — if the user asks for a change, say plainly that this integration cannot write to NetBox rather than implying you will. (2) `detail` defaults to `compact` (useful fields, each relation collapsed to `{id, display}`); `brief` is id/display/name only; `full` is the raw ~60-field object — ask for it only for a single record, a page of full objects is tens of KB. (3) Every result carries a **`web_url`** — cite THAT when pointing a human at a record, never a URL you assembled. (4) The `users`, `core` and `secrets` apps are deliberately unreachable: they expose accounts, permissions, API tokens and stored credentials rather than inventory. Plugin apps are allowed one at a time by name (today: `inventory`), never as a namespace. (5) A **timeout** almost always means a source-IP ACL on the NetBox side, not a bad token — the error message says so. (6) `netbox_schema` reports its fields under `actions.POST`/`actions.PUT` — NetBox exposes the field schema there, never under `GET`. With a strictly read-only token NetBox may omit `actions` entirely; the tool then returns `fields: null` with a note, which is a permission limit, not a missing model. ### Snipe-IT tools (`snipeit` scope) Read-only access to connected **Snipe-IT** instances — an IT asset register (hardware, who has it, license seats, accessories, locations, check-out history). Workspace-scoped: every instance in any of the user's Lynk workspaces is reachable. The Snipe-IT personal API token is stored AES-256-GCM encrypted; the underlying client sends only `GET`, so **this scope has no write path at all**. `instance_id` is OPTIONAL on every tool — omit it when the user has exactly one Snipe-IT connection; with several, the error lists the choices. - `snipeit_list_instances` — `{}` → every connection (`id`, `name`, `base_url`, `api_user` = the Snipe-IT account reads run as, `snipeit_version`, `last_test_ok`, `last_test_error`, `instance_context`, `instance_dont`). **Call first.** - `snipeit_update_instance_config` — `{ instance_id?, instance_context?, instance_dont? }` → persist per-instance AI facts/guardrails (any workspace member). "" / null clears. Does NOT touch Snipe-IT. - `snipeit_find_asset` — `{ instance_id?, asset_tag? | serial? | query?, limit?, detail? }` → exactly one of the three. `asset_tag` = exact match (one asset); `serial` = list (serials are not unique); `query` = free-text hardware search. - `snipeit_list` — `{ instance_id?, resource, search?, filters?, sort?, order?, limit?, offset?, detail? }` → `resource` ∈ `hardware`, `users`, `licenses`, `accessories`, `consumables`, `components`, `locations`, `models`, `categories`, `manufacturers`, `statuslabels`, `companies`, `departments`, `suppliers`, `depreciations`, `fieldsets`. `filters` are Snipe-IT's own list params and take **numeric ids** (`{"status_id":3}`, `{"model_id":12}`, `{"location_id":4}`) — resolve a name with a list call on that resource first. Hardware also accepts `{"status":"RTD"|"Deployed"|"Requestable"|"Undeployable"|"Archived"}`. Default page 50, max 500; continue with `next_offset`. - `snipeit_get` — `{ instance_id?, resource, id, detail? }` → one record. - `snipeit_user_items` — `{ instance_id?, user_id? | email? | username?, detail? }` → hardware + license seats + accessories checked out to that **person**. An ambiguous email/username match returns `candidates` instead of guessing. Items checked out to a location or another asset are not included. - `snipeit_activity` — `{ instance_id?, item_type?, item_id?, target_type?, target_id?, action_type?, limit?, offset? }` → the activity log newest-first (checkouts, checkins, updates, audits, deletions + who did them). `item_type` ∈ asset/accessory/license/consumable/component/user; `target_type` ∈ user/asset/location. **Rules:** (1) **Read-only** — if the user asks for a check-out, check-in or edit, say plainly that this integration cannot write to Snipe-IT. (2) `detail` defaults to `compact`: UI plumbing (`available_actions`, image urls) dropped, relations collapsed to `{id, name}` (+ `username`/`email`/`type` for the assignee), dates flattened, `custom_fields` turned into a `label → value` map, HTML entities decoded (Snipe-IT escapes every string server-side). `full` = the raw object. (3) Every result carries a **`web_url`** — cite THAT. (4) Snipe-IT often answers "not found" with HTTP 200 + `{"status":"error"}`; the client turns that into a real not-found error, so an empty success never masks a miss. (5) A **timeout** means the instance is only reachable from a VPN or allowlisted source IP — the error names the gateway address to allowlist. (6) `settings`, personal-access-token and import/backup endpoints are unreachable by construction (resource allowlist). ### Elastic tools (`elastic` scope) **READ-ONLY.** This integration cannot index, update, delete or reindex anything. Three guards run before a request leaves Lynk, and they hold regardless of what the stored credential is allowed to do: 1. **Endpoint allowlist** — `_bulk`, `_delete_by_query`, `_update_by_query`, `_reindex`, `_update`, `_scroll`, `_security`, `_ilm`, `_snapshot`, `_scripts`, `_ingest` and `_watcher` are unreachable. `POST /<index>/_doc` (which writes) is refused while `GET /<index>/_doc/<id>` (which reads) is allowed. 2. **Index targets** — anything starting with `.` (system/hidden), a bare `*` / `_all`, and cross-cluster `remote:index` targets are refused, on the DSL path **and** inside an ES|QL `FROM`. The security index stores API-key hashes, so a read there is a credential leak rather than a query. 3. **Query body** — `script`, `script_fields`, `runtime_mappings`, `scroll` and `pit` are refused anywhere in the body. Elasticsearch READ privileges alone do **not** stop a search from executing Painless, which is why this guard exists rather than being left to the credential. **The shortest path to an answer:** ``` elastic_list_indices({}) → data-stream / alias names + each timestamp field elastic_field_caps({ pattern: "logs-*" }) → the real field names (do NOT guess them) elastic_esql({ query: "FROM logs-* | WHERE @timestamp >= NOW() - 1 hour | STATS n = COUNT(*) BY log.level" }) ``` - `elastic_list_instances` — `{}` → every connected cluster (`id`, `name`, `es_url`, `es_version`, `es_flavor`, `index_patterns`, `kibana_configured`, `security_enabled`, `credential_can_write`, `instance_context`, `instance_dont`). **Call first.** Read `instance_context` (which index holds what, naming conventions) and `instance_dont` before querying. - `elastic_update_instance_config` — `{ instance_id?, instance_context?, instance_dont? }` → persist per-connection facts/guardrails. `""`/null clears. Does NOT touch the cluster. - `elastic_list_indices` — `{ instance_id?, pattern? }` → indices, aliases and data streams with `timestamp_field` and (where the credential allows) `docs_count`. **Query the data-stream or alias name, never the `.ds-…` backing index.** Built on `_resolve/index`, which needs fewer privileges than `_cat` and works on serverless. - `elastic_field_caps` — `{ instance_id?, pattern }` → `{ name, types, searchable, aggregatable }`. Call this **instead of guessing** — a query against a field that does not exist returns zero hits, which is indistinguishable from "no matching data". - `elastic_esql` — `{ instance_id?, query }` → `{ columns, rows, row_count, truncated }`. **The preferred query tool.** ES|QL is piped (`FROM … | WHERE … | STATS … | SORT … | LIMIT …`) and cannot write by construction — its parser has no write commands. Bound the time range in the query, use `KEEP` to name your columns, and prefer `STATS` over fetching documents. Needs Elasticsearch 8.11+; `elastic_list_instances` says whether the cluster has it. - `elastic_search` — `{ instance_id?, indices, body?, size?, fields?, time_field?, from?, to? }` → projected hits + aggregations. The escape hatch for what ES|QL cannot express and for clusters below 8.11. Pass `from`/`to` rather than writing a range filter — Lynk injects it. `size: 0` + `aggs` aggregates without returning documents. Hits are **projected** (flattened, ECS-default fields, long values truncated), never raw `_source`. **`total.relation: "gte"` means the count is capped — never report it as exact.** - `elastic_get_document` — `{ instance_id?, index, doc_id }` → one document from one concrete index (not a pattern). - `elastic_list_data_views` — `{ instance_id? }` → Kibana's curated index patterns with their time field. The organisation's own answer to "where does this data live". - `elastic_list_saved_objects` — `{ instance_id?, type?, limit? }` → dashboards, saved searches, visualisations. These document what people in this organisation actually look at. The heavy `fields` attribute is stripped. - `elastic_list_alerts` — `{ instance_id?, limit? }` → `{ alerts, sources, total }`. **Read `sources` before concluding anything**: it names every alerting system asked and what each returned, so an empty `alerts` list caused by a missing Kibana URL or missing privileges is never mistaken for "nothing is alerting". - `elastic_cluster_health` — `{ instance_id? }` → status, node and shard counts. Reports `available: false` with a reason (rather than a fabricated green) when the credential lacks `cluster:monitor` or the deployment is serverless. **Kibana is optional and needs its own privileges.** An Elasticsearch-only API key authenticates against Kibana but carries no Kibana feature privileges: `data views` and `saved objects` come back as an **EMPTY LIST rather than an error**, and alerting is refused. So an empty result there may mean missing permissions, not missing data — `elastic_list_instances` and the connection test say which. **PII.** Log and APM documents are the most PII-dense data most organisations hold. Count and aggregate first; fetch raw documents last and only as many as the question needs. ### Grafana tools (`grafana` scope) Read a connected **Grafana**: dashboards (and the queries behind their panels), datasources, folders, metric queries and alerts. Workspace-scoped — an instance is reachable if you are a member of the workspace that owns it. `instance_id` is optional everywhere: omit it when you have exactly one connection, otherwise the error lists the choices. **READ-ONLY** — no tool here can create or change anything in Grafana. **The normal path to a number is three calls, and skipping to the last one does not work:** metric names are not guessable and Grafana exposes no browsable metric catalogue, so the DASHBOARDS are the documentation. ``` grafana_search_dashboards({ query: "power" }) → find the dashboard that already plots it grafana_get_dashboard({ uid }) → read the panel's PromQL / SQL + its datasource uid grafana_query({ datasource, query }) → run it (substituting any $variables) ``` - `grafana_list_instances` — `{}` → every connected instance (`id`, `name`, `base_url`, `grafana_version`, `last_test_ok`, `instance_context`, `instance_dont`). **Call first.** Read `instance_context` (which datasource holds what, what the site/rack naming means) + `instance_dont` before answering. - `grafana_update_instance_config` — `{ instance_id?, instance_context?, instance_dont? }` → persist per-instance AI facts/guardrails (any workspace member). "" / null clears. Does NOT touch Grafana. - `grafana_search_dashboards` — `{ instance_id?, query?, tag?, folder_uid?, limit? }` → `{ uid, title, folder, tags, url }`. Search by SUBJECT ("power", "rack", "latency", "postgres"), not by metric name. - `grafana_get_dashboard` — `{ instance_id?, uid }` → the dashboard **including every panel's `targets`**, i.e. the literal PromQL (`expr`) or SQL (`rawSql`) it runs plus the datasource uid to run it against. Also returns `templating` (the dashboard's `$variables` with their `current` value and a sample of options). Panels inside collapsed rows are included. Styling (`fieldConfig`, `options`) is stripped — it answers no question and runs to tens of KB. - `grafana_list_datasources` — `{ instance_id?, refresh? }` → `{ uid, name, type, kind }`. `kind` decides the query language: `prometheus` → PromQL, `sql` → SELECT-only SQL, `alertmanager` → not directly queryable (it is what `grafana_list_alerts` reads), `other` → not addressable. A dashboard panel already names its datasource uid, so you often do not need this call. - `grafana_query` — `{ instance_id?, datasource, query, kind?, start?, end?, step?, from?, to?, max_rows? }` → rows. PromQL: `kind:'instant'` (default) gives the current value per series with the metric's labels flattened onto each row; `kind:'range'` gives a series per row (`values: [[iso, number], …]`) and takes `start`/`end`/`step`. SQL: takes `from`/`to` for Grafana's `$__timeFilter` macros. Capped at 1000 rows — `truncated: true` means narrow the query, not paginate. - `grafana_list_alerts` — `{ instance_id?, state?, limit? }` → `{ alerts, rules, counts, sources }`. `alerts` are active alert INSTANCES (from Alertmanager), `rules` are alerting RULES and their state (from Prometheus) — one rule can produce many instances, so the counts legitimately differ. `sources` names every system asked and what each returned, so a 0 from one (Grafana's own alerting commonly returns 0 while an external pair reports hundreds) never becomes the whole answer. **`counts` are per SOURCE, not distinct**: two Prometheis sharing a rule file evaluate it independently, so the same rule appears once per source with its own state and `active_count` — quote a figure with its source rather than merging rows by name. - `grafana_list_folders` — `{ instance_id?, limit? }` → `{ uid, title }`, for orienting yourself and for narrowing a dashboard search. **Rules:** (1) **Read-only** — if the user asks for a dashboard or alert-rule change, say plainly that this integration cannot write to Grafana rather than implying you will. (2) **Do not invent metric names.** Get the query from a panel via `grafana_get_dashboard`; a guessed metric silently returns an empty result, which looks like "the value is zero". (3) A panel query containing a `$variable` will NOT run as-is — substitute a concrete value from `templating` first; likewise replace Grafana's `$__range` / `$__timeFilter` macros with a real range when you run a query yourself (`grafana_query` passes `from`/`to` through for SQL). (4) **SQL is SELECT-only and enforced server-side**: a single statement starting with SELECT / WITH / SHOW / DESCRIBE / EXPLAIN, with write verbs rejected wherever they appear (including inside a CTE). Do not attempt a write to "check" something. Always add a LIMIT to an exploratory SELECT. (5) **Alerting may not live in Grafana's own alerting.** Where it runs on an external Prometheus/Alertmanager pair, Grafana's built-in alert API reports ZERO rules while hundreds of alerts are firing — so `grafana_list_alerts` reads the alerting datasources and returns a `sources` list naming every system it asked and what each returned. If one source reports 0, say WHICH one; never turn that into "nothing is alerting". (6) A **timeout** almost always means a source-IP ACL on the Grafana side, not a bad token — the error message says so. ### Testify (scope: `testify`) Set up + read Testify — guided test sessions recorded by external testers on public recording links (screen + voiceover + a tickable test-plan checklist), processed into transcript + storyboard + timeline events. Sessions come in two modes: `recorded` (screen + voice video, the default) and `text` (NO video — the tester only ticks the plan and types per-step findings; the voiceless / headless / AI-tester path). Agents can create a project + a distributable recording link, invite testers by email (`testify_invite_testers`) AND file a text report directly (`testify_submit_text_report`); other report management (delete, settings, revoke) stays in the dashboard. Every response carries a `view_url`. - `testify_list_projects` — `{}` → your test projects across all workspaces (id, name, report_count, view_url) **plus `sdk_key` + a ready-to-paste `sdk_snippet`** (the `<script src="https://lynk.run/sdk/testify.js" data-key="tsp_…" async>` tag). **Call first.** Use `sdk_snippet` to install in-app telemetry + the test-plan overlay into the app under test (staging build) for an EXISTING project — no need to re-create it. - `testify_create_project` — `{ name, handbook_md?, workspace_id? }` → create a project (id + `tsp_…` sdk_key + ready `sdk_snippet`). Omit `workspace_id` for your personal workspace. The `handbook_md` markdown is shown to every tester. - `testify_create_link` — `{ project_id, title?, plan_md?, target_url?, max_uses?, expires_in_days? }` → a distributable recording link `https://lynk.run/rec/<token>` to hand to testers (no account/extension; record in-browser). Numbered `plan_md` lines ("1. …", "2) …") become the tester's checklist; `target_url` adds an "Open test app" button + enables SDK pairing; `max_uses`/`expires_in_days` (0 = never) cap the link. The response's `id` is the internal link id — pass it to `testify_invite_testers`. - `testify_invite_testers` — `{ link_id, emails }` → invite testers to a recording link by email. `link_id` is the link's internal `id` (from `testify_create_link`, NOT the public token). Each address gets a personalised recording URL and an email is **sent automatically** (subject "You're invited to test <project>", with the test plan + a "Start the test →" button). **Idempotent per (link, email)** — an already-invited address is skipped, never re-mailed (use it only to add NEW testers; resend lives in the dashboard). These are real emails to real people — confirm the list with the user first. Returns `{ invites, created, sent, email_configured }`; if `email_configured` is false the invites exist but no mail went out (share the personalised URL manually). - `testify_submit_text_report` — `{ link_token, tester_name?, notes?, steps? }` → file a **TEXT (no-video) report** against a recording link in ONE call — the headless / AI-tester path. `link_token` is the `<token>` in `https://lynk.run/rec/<token>` (the full URL works too). `steps` is `[{ n, passed?, note? }]` — `passed:false` and/or a `note` marks a finding; each `note` becomes a step-linked finding fed to the auto-issue extractor (same as a tester typing it). Returns `{ report_id, status:'processing', mode:'text', view_url }`; issues extract automatically. **You must be a member of the link's workspace** (this authenticated tool is the project-owner side; the public token-only flow is the browser recorder). - `testify_list_reports` — `{ project_id }` → reports newest-first (status, `mode` ('recorded'|'text'), duration_sec, tester_name, checklist outcome summary, has_transcript, event/frame counts). - `testify_get_report` — `{ report_id }` → full metadata: `mode` ('recorded'|'text'), `steps_result` (each plan step with `ticked_at_ms` timestamp or null = skipped), tester notes, storyboard timestamps, `issue_count`. **Start here.** A skipped step is the strongest "something broke here" signal. A `text`-mode report has no video/transcript/storyboard — read `testify_get_issues` + `testify_get_events`. If `issue_count > 0`, call `testify_get_issues` next. - `testify_get_issues` — `{ report_id }` → the issues auto-extracted at processing time (LLM over the tester's voiceover transcript + captured console/network/errors). Each: `title`, `detail`, `severity` (low/medium/high), `ts_ms` (where it surfaced), `frame_ms` (nearest storyboard frame — pass to `testify_get_frame` for the screenshot), and `console` (the console/network events in its time window). **Usually the fastest, most actionable read of a report — prefer it over re-deriving issues from the raw transcript.** - `testify_get_transcript` — `{ report_id }` → the voiceover as timestamped WebVTT. Mute recordings have none (that's not an error). - `testify_get_events` — `{ report_id, kinds?, from_ms?, to_ms? }` → timeline events: `step` (checklist ticks), `issue` (tester's "Mark issue" markers, often with a note); `console`/`network`/`click` once the in-app SDK is installed. Filter to stay focused. An `issue` event may carry an `annotation` object — the tester DREW on the screen (SDK pen tool): `annotation.anchors` names the UI element under each stroke/box/comment (`at`), its viewport bounding box (`box`/`pin`) and a coarse `region` ("top-right", …) — the machine-readable WHERE; in a recorded session the sketch is also baked into the video frame at the event's `ts_ms` (`testify_get_frame`). - `testify_get_storyboard` — `{ report_id, max_frames? }` → scene-change thumbnails (images) captioned with timestamps — the cheap visual overview. - `testify_get_frame` — `{ report_id, ts_ms }` → one full-resolution JPEG at a millisecond offset (extracted on demand, cached). Be frugal: text first, a handful of targeted frames second. All timestamps are milliseconds from recording start and shared across transcript/events/storyboard/frames (one clock). Reports auto-delete 30 days after completion. ### Voice tools (`voice` scope) ElevenLabs text-to-speech + sound effects. **BYOK** — every generation runs against the USER's OWN connected ElevenLabs key (encrypted at rest, per-user). The user pays ElevenLabs directly; **Lynk charges NO tokens**. If no key is connected, every voice tool returns an error telling the user to connect one at `https://api.lynk.run/voice`. Every generation returns a downloadable URL — MCP can't return raw audio bytes. By default the audio is a public `https://lynk.run/dl/<id>` shared file; pass `store_to: { bucket, key }` to write it into your bucket object store at a STABLE address instead (the audio-manifest path: first run uploads, later runs overwrite the same key). Identical requests reuse a per-user cache — a `cached: true` result skips the upstream call (saves your own ElevenLabs quota). - `voice_list_voices` — `{}` → `{ voices: [{ voice_id, name, category?, description?, preview_url?, labels? }], count }` (the caller's own account voices). **Call first** to get a `voice_id`. - `voice_tts` — `{ text, voice_id, model_id?, output_format?, language_code?, voice_settings?, seed?, previous_text?, next_text?, store_to?, filename?, expires_in_days?, no_cache? }` → `{ audio_url | stored:{bucket,key,size}, format, mime, characters, cached }`. `voice_settings` = `{ stability?, similarity_boost?, style?, use_speaker_boost?, speed? }`. Default model `eleven_flash_v2_5`, default format `mp3_44100_128`. `previous_text`/`next_text` give continuity across split clips. - `voice_sound_effect` — `{ text, duration_seconds?, prompt_influence?, output_format?, store_to?, filename?, no_cache? }` → same result shape (no `characters`). `text` is the sound-effect prompt. - `voice_music` — `{ prompt, music_length_ms?, force_instrumental?, model_id?, output_format?, seed?, store_to?, filename?, expires_in_days?, no_cache? }` → same result shape. Composes a music track from a text prompt. `music_length_ms` bounds the length (3000–600000 ms; omit to let the model choose). `force_instrumental` drops vocals; `seed` makes a prompt reproducible. Default model `music_v2`. - `voice_batch` — generate MANY narration clips in ONE call (the **audiobook engine**). `{ items:[{ key, text, voice_id?, model_id?, output_format?, language_code?, voice_settings?, seed? }], defaults?:{ voice_id?, model_id?, output_format?, language_code?, voice_settings?, seed?, bucket?, key_prefix?, expires_in_days? }, stitch?, concurrency?, no_cache? }` → a manifest `{ items:[{ key, ok, characters, cached?, format?, bucket?, object_key?, size?, audio_url?, id?, error? }], total, succeeded, failed, characters_total, key_rejected, stitched }`. Each item's `key` is its logical id AND (with `defaults.bucket`, auto-created) its object key (`key_prefix + key`); without a bucket each clip is a `/dl/` shared file. **CONSISTENCY: set `stitch: true`** to auto-wire each item's `previous_text`/`next_text` from its neighbours so the narrator reads the whole ordered sequence as ONE continuous performance — combine with a single `defaults.voice_id` + locked `defaults.voice_settings` + a fixed `defaults.seed` for a stable narrator. Order matters when stitching. Max 200 items/call, each ≤ 5000 chars — split long text into ordered items yourself first. - `voice_request` — `{ path }` → READ-ONLY escape hatch for ElevenLabs catalog endpoints not wrapped first-class. GET only, whitelisted to `/voices`, `/models`, `/shared-voices`, `/pronunciation-dictionaries` (account-admin endpoints are deliberately unreachable). Runs against your own key. Voice-role mapping (e.g. `benny`→`voice_id`) and audio manifests are the consuming app's job — Lynk's API is a generic voice capability, not app-specific. ### SSH tools (`ssh` scope) Register servers as connections (in the dashboard at `https://api.lynk.run/ssh` or with `ssh_create_connection`), then run shell commands and transfer files over SSH on them. A key can back many hosts; connections are per-connection shareable. Execution is ONE-SHOT — each call opens a fresh connection, runs, and closes, so shell state (working directory, env vars, background processes) does NOT persist across calls. The "session" that carries a back-and-forth diagnosis is THIS MCP conversation, not a remote shell. Every command is audit-logged. **No Lynk tokens are charged** (the user brings their own servers). **SAFETY — you are executing real commands on real servers.** ALWAYS call `ssh_list_connections` FIRST and read each connection's `instance_context` (host facts) + `instance_dont` (hard guardrails you MUST obey). For any DESTRUCTIVE or irreversible action (delete, restart/stop a service, drop data, overwrite files, reboot) CONFIRM with the user before running — never run it autonomously. A `host_key_mismatch` error means the server's host key changed (possible MITM or a rebuild) — do NOT retry; tell the user to verify and reset the pinned key in the dashboard. - `ssh_create_connection` — `{ name, host, username, port?, auth_method?, private_key?|key_id?|password?, passphrase?, key_name? }` → `{ connection, test }`. Register a NEW connection you own (inline `private_key` is vaulted encrypted, or reuse a `key_id`, or `password`); auto-tests + TOFU-pins the host key. Secrets are never returned. Owner-only write — call only when the user asked to register a server. - `ssh_list_connections` — `{}` → `{ connections: [{ id, name, host, port, username, auth_method, is_owner, owner_email, is_readonly, command_allowlist, host_key_pinned, last_test_ok, instance_context, instance_dont }] }`. Use `id` as `connection_id` everywhere else. Read `instance_context` + `instance_dont` before acting. - `ssh_run` — `{ connection_id, command, stdin?, timeout_ms? }` → `{ stdout, stderr, exit_code, signal, truncated, duration_ms }`. One-shot; chain with `&&` or use absolute paths (`cd /var/log && tail -n100 syslog`), `bash -lc "…"` for a login-shell env. Pipe `stdin` for prompts (sudo -S, a DB REPL). `timeout_ms` default 60s, max 10min. stdout/stderr each capped at 1MB (`truncated: true` when hit). Read-only connections reject obviously-destructive commands + anything off their allowlist (best-effort guardrail, not a hard sandbox). - `ssh_upload` — `{ connection_id, remote_path, content_base64 }` → `{ ok, bytes, remote_path }`. SFTP put (≤100MB). Blocked on read-only connections. - `ssh_download` — `{ connection_id, remote_path }` → `{ ok, bytes, content_base64 }`. SFTP get (≤100MB). - `ssh_update_connection` — `{ connection_id, name?, host?, port?, username?, auth_method?, private_key?|key_id?|password?, passphrase?, key_name? }` (owner-only) → `{ connection, retargeted, credential_changed, test }`. Edit a connection in place (the box moved IP/port, the login user changed, the key/password rotated) — keeps the id, so `ssh_run` and any sharing keep working. **Omit = keep** for every field, and credentials are OPT-IN: pass a credential ONLY to replace it. Changing host/port clears the pinned host key + the last-test verdict (the pin belonged to the old machine; keeping it would fail the next connect with a `host_key_mismatch` that is NOT an attack), a credential change clears the verdict — both are re-established by the auto-test whose result comes back as `test`. A failed test does NOT undo the edit. Secrets are never returned. WRITE action that can cut off access to a live server: confirm with the user first. - `ssh_update_connection_config` — `{ connection_id, instance_context?, instance_dont? }` (owner-only) → persists host facts + guardrails you learn from the user (does NOT change anything on the server). "" clears a field, omit keeps it. Use THIS, not `ssh_update_connection`, when only the AI context or guardrails change. ### Brain tools (`brain` scope) The workspace **Brain** — a standalone, workspace-scoped team knowledge base built on the Obsidian model: markdown notes whose titles form a `[[wikilink]]` namespace (unique per workspace, case-insensitive). A wikilink to a note that doesn't exist yet is fine — it resolves the moment that note is created ("ghost" links), and deleting a note just makes links to it unresolved again. Renaming a note automatically rewrites `[[Old Title]]` in every linking note. Inline `#tags` in bodies are picked up automatically. `![[Title]]` on its own line embeds the target note's content in the dashboard viewer (transclusion, one level deep — and an embed counts as a link). Every content-changing save snapshots a version (history + restore live in the dashboard — no MCP version tools). Every tool takes an optional `workspace_id` (id or slug); omitted = your personal workspace. Any workspace member reads + writes. **No tokens charged.** **Intended flow:** `brain_search` → `brain_get_note` (read the full note + follow its `links`/`backlinks`) BEFORE answering questions about the team's internal knowledge; write learnings back with `brain_create_note` / `brain_update_note` — link generously with `[[Other Note]]` so the graph grows into a real company brain. - `brain_search` — `{ query, workspace_id?, limit? }` → `{ total, has_more, results[] }`: FTS5 hits across titles/bodies/tags (prefix-matched), re-ranked so title matches come first and hub/index notes (many `backlinks`) outrank their own child notes. Each hit: `{ id, title, tags, excerpt, matched_in: ('title'|'body'|'tags')[], backlinks, updated_at }`. The `excerpt` carries NO highlight marks and keeps `[[wikilinks]]` intact — a `[[Title]]` in it can be passed straight to `brain_get_note { title }`. Read high-`backlinks` hits first (they map the topic); `matched_in: ["tags"]` alone means the note is filed under the topic rather than about your exact words; `has_more: true` means the page did not cover every match (raise `limit` or narrow the query). - `brain_get_note` — `{ id? | title?, workspace_id? }` → the full note (markdown body) + `links` (outgoing wikilinks; `to_note_id: null` = target doesn't exist yet) + `backlinks` (notes linking here) + `unlinked_mentions` (notes mentioning this title as plain text without linking it — suggest linking them) + `embeds` (resolved `![[Title]]` transclusion targets, one level deep). - `brain_list_notes` — `{ workspace_id?, tag?, limit?, offset? }` → metadata + preview, most recently updated first. - `brain_create_note` — `{ title, body_md?, tags?, workspace_id? }` → create. Titles must not contain `[ ] | #` or line breaks (they ARE the wikilink target). Use `[[Note Title]]` links + inline `#tags` in the body. - `brain_update_note` — `{ id, title?, body_md?, append?, tags?, workspace_id? }` → in-place update, "omit = keep". `append: true` concatenates `body_md` onto the existing body (the cheap "add a learning" path). A `title` change rewrites wikilinks in every linking note and reports `renamed_links_in`. - `brain_delete_note` — `{ id, workspace_id? }` → permanent delete (links to it become unresolved). Only when the user clearly asked. - `brain_graph` — `{ workspace_id? }` → `{ nodes, edges, ghosts, truncated }` — the knowledge graph. `ghosts` are linked-to titles with no note yet (good candidates to write next). - `brain_list_tags` — `{ workspace_id? }` → every tag with its note count (the topic map). ### Caya tools (`caya` scope) **Caya** is a digital mailroom — a service that scans a user's physical postal mail into PDFs organised in folders. Lynk talks to Caya's private backend on the user's behalf (Caya has no public API). Connections are strictly **PERSONAL** (scoped to the signed-in user, never shared) and hold the user's Caya login — Caya carries sensitive personal mail (invoices, official letters), so document PDFs come back **inline in the tool result, never as a public link**. No Lynk tokens charged. **Intended flow:** `caya_list_instances` → `caya_list_folders` (no `parent_id` → the inbox/archive/trash ids) → `caya_list_documents` on a folder → then read (`caya_download_document`) or sort (`caya_move` / `caya_trash` / `caya_mark_read` / `caya_tag`). Every id you pass comes from one of the list tools — folder ids from `caya_list_folders`, document/container ids from `caya_list_documents`. - `caya_list_instances` — `{}` → the caller's Caya connections (`id`, `name`, test status). Use the `id` as `instance_id` everywhere else. - `caya_list_folders` — `{ instance_id, parent_id? }` → omit `parent_id` for the three SYSTEM folders (`{ inbox, archive, trash }` as container ids — the entry point); pass a folder id to list its sub-folders. - `caya_list_documents` — `{ instance_id, folder_id }` → the documents in a folder: `{ id, filename, sender, subject, created_at, pages, file_url }`. - `caya_download_document` — `{ instance_id, folder_id, document_id }` → `{ filename, content_type, size, content_base64 }`. You must pass BOTH the folder and the document id (the folder is re-listed server-side to resolve the signed URL — no caller-supplied URL). Files > 20 MB are refused (download from the dashboard instead). - `caya_move` — `{ instance_id, ids: string[], to_folder }` → move documents/folders into a target folder (how you sort mail). This is the sort primitive. - `caya_trash` — `{ instance_id, ids: string[] }` → soft-delete (moves to the Trash folder). - `caya_mark_read` / `caya_mark_unread` — `{ instance_id, ids: string[] }`. - `caya_tag` — `{ instance_id, document_id, tags: string[] }` → add categorisation tags to one document. - `caya_create_folder` — `{ instance_id, title, parent_id? }` → new folder (root unless `parent_id`); returns its id (use as a `to_folder`). - `caya_rename_folder` — `{ instance_id, folder_id, title }`. ## Session lifecycle The server is stateful per session. Your client receives an `mcp-session-id` header on the `initialize` response and must include it on every subsequent request in this session. Sessions are pruned after 1 hour of inactivity — measured from the last request on the session, so an in-use session is never pruned out from under you. Calling `DELETE /mcp` (with the session header) ends the session cleanly. Only `initialize` opens a session. Any other request that doesn't resolve to a live session — a stale id, or no `mcp-session-id` header at all — is answered `404` with `{"error":{"code":-32001,"message":"Session not found — reinitialize"}}`; re-send `initialize` and continue on the new id. ## Token revocation & client management Users manage authorized clients at `https://api.lynk.run/settings/mcp`. The page lists every MCP client that currently holds valid access/refresh tokens, with a single-click revoke button. Revoking a client invalidates **all** tokens (access + refresh) issued to that `client_id` for that user. ## See also - Intel API spec: https://intel.lynk.run/llms.txt - Web dashboard & docs: https://api.lynk.run/docs - Per-user MCP setup: https://api.lynk.run/settings/mcp - Source / issues: https://github.com/jpj069/lynk-site

# Lynk MCP Server — Model Context Protocol endpoint > Lynk exposes its APIs (Intel, BGP, Domains, Web Search, Scrape, Tech Scanner, Files, Deskpro, NetSuite, Salesforce, CRM, GEO, generic request escape-hatch) as MCP tools so AI agents in IDEs (Claude Desktop, Cursor, Cline, Zed, Roo Code) can call them natively. OAuth 2.1 with PKCE — no API keys in client config files. This file follows the llms.txt convention. If you are an MCP-capable agent and the user wants to connect Lynk, point them here. ## Endpoint ``` https://api.lynk.run/mcp ``` Transport: **Streamable HTTP** (MCP spec 2025-06-18 or newer). HTTP+SSE is not supported. **Wunderbox Kids Studio content authoring has its OWN dedicated endpoint on its own origin**, separate from this one so its tools don't bloat the main surface: `https://wunderbox.app/mcp` (scope `wunderbox`, same OAuth authorization server at api.lynk.run). See https://wunderbox.app/mcp/llms.txt. ## Quick setup ### Claude Desktop (`claude_desktop_config.json`) ```json { "mcpServers": { "lynk": { "url": "https://api.lynk.run/mcp" } } } ``` ### Cursor (`.cursor/mcp.json`) ```json { "mcpServers": { "lynk": { "url": "https://api.lynk.run/mcp" } } } ``` ### Cline / Roo Code (`cline_mcp_settings.json`) ```json { "mcpServers": { "lynk": { "type": "streamableHttp", "url": "https://api.lynk.run/mcp" } } } ``` On first launch, your MCP client opens a browser for the OAuth consent screen. Approve the requested scopes once; the client stores the access + refresh tokens transparently and re-uses them thereafter. ## Authentication (OAuth 2.1) - **Discovery**: `GET /.well-known/oauth-authorization-server` (RFC 8414) and `GET /.well-known/oauth-protected-resource` (RFC 9728). The resource metadata is served under **both** the root path and the RFC 9728 path-inserted form derived from the resource identifier — `GET /.well-known/oauth-protected-resource/mcp` — so a client can bootstrap either from our `WWW-Authenticate` header or by deriving the URL itself (MCP 2025-11-25 / SEP-985 made that header optional, with the `.well-known` derivation as the fallback). - **DCR**: `POST /oauth/register` (RFC 7591). Public clients only (`token_endpoint_auth_method=none`, PKCE-mandatory). No `client_secret`. - **Authorize**: `GET /oauth/authorize?response_type=code&client_id=...&redirect_uri=...&code_challenge=...&code_challenge_method=S256&scope=...&state=...&resource=https://api.lynk.run/mcp`. PKCE S256 is required; `plain` is rejected. - **Token**: `POST /oauth/token` with `grant_type=authorization_code` (initial) or `grant_type=refresh_token` (rotation). Refresh tokens rotate; reusing a rotated refresh token revokes the whole chain (RFC 6749 §10.4). - **TTLs**: access token 1 h, refresh token 30 d, authorization code 10 min. - **Revoke**: `POST /oauth/revoke?token=` (RFC 7009). - **Audience binding** (RFC 8707): tokens are issued for `resource=https://api.lynk.run/mcp` and rejected if presented to a different audience. Always send `resource` on `/oauth/authorize` — the dedicated `wunderbox.app/mcp` and `studio.lynk.run/mcp` resources reject any token that isn't explicitly bound to them. - **Origin**: the Streamable HTTP endpoints validate the `Origin` header and answer **403** for one that isn't allow-listed (MCP 2025-11-25). Native MCP clients send no `Origin` and are unaffected; this only constrains browser-based clients. When a request to `/mcp` arrives without (or with an invalid) Bearer token, the server responds with `401` and a `WWW-Authenticate: Bearer realm="lynk-mcp", resource_metadata="..."` header pointing at the resource metadata document — your client should use that to bootstrap. ## Available scopes | Scope | What it grants | |-------|----------------| | `intel` | `intel_lookup` — IP & domain intelligence (geo + ASN from 7 providers, DNSBL, DNS, WHOIS, SSL, mail provider) | | `bgp` | `bgp_company_search` — find a company's ASNs, announced prefixes, total IP count, BGP relationships | | `domains` | `domain_check` — ultra-fast domain availability checker (is a domain free to register?) · `domain_check_status` — poll a background sweep · `domain_tlds` — the supported endings | | `search` | `web_search` — Google web-search results (organic + answer box + knowledge graph + PAA + related), JSON or LLM-friendly Markdown output | | `scrape` | `scrape_page`, `scrape_crawl_start`, `scrape_job_status`, `scrape_extract` — web scraping, async deep crawls, LLM-based extraction | | `files` | `files_list`, `files_delete`, `files_upload` — upload a file and get a public `https://lynk.run/dl/` link (optional password + expiry), list and delete your shared files. PLUS a per-user S3-style **bucket** object store: `bucket_list`, `bucket_create`, `bucket_delete`, `bucket_list_objects`, `bucket_put_object`, `bucket_get_object`, `bucket_delete_object` — a stable `(bucket, key)` address for artifacts (upload once, fetch deterministically every later run with no opaque file id to persist; the natural path for CI + bulk transfer). Uploads take inline `content_base64` OR a server-side SSRF-guarded `source_url` fetch. No tokens charged. | | `request` | `lynk_request` — generic escape hatch for whitelisted Lynk endpoints not yet wrapped as dedicated tools | | `deskpro` | `deskpro_list_instances`, `deskpro_list_tickets`, `deskpro_get_ticket`, `deskpro_create_ticket`, `deskpro_reply_ticket`, `deskpro_save_draft_reply`, `deskpro_update_ticket`, `deskpro_search_people`, `deskpro_get_organization`, `deskpro_search_organizations`, `deskpro_download_attachment`, `deskpro_upload_attachment` — manage tickets, people, and organizations across your connected Deskpro instances (including ones other Lynk users shared with you). Every ticket-bearing response includes `ticket_url` — the canonical AGENT-UI deep link (`/app#/t/ticket/`). Always cite that URL to operators; the end-user portal URL (`/tickets/`) 404s for agents. Both `deskpro_create_ticket` and `deskpro_reply_ticket` accept `is_agent_note: true` to make the (first / new) message an internal agent note instead of a customer-visible reply — the requester is NOT notified. Use that for test or internal-triage tickets. Converting an existing note into a customer reply is intentionally NOT exposed: the only Deskpro path that flips a note AND mails the customer is the agent-UI button "Set Note as Reply"; the API flip (`PUT is_note:false`) is silent. To get a customer mail out, post a fresh reply with `deskpro_reply_ticket`. Every `deskpro_list_instances` entry carries `instance_context` (account facts) + `instance_dont` (hard guardrails) — read both before acting; persist them with the owner-only `deskpro_update_instance_config`. | | `netsuite` | `netsuite_list_instances`, `netsuite_suiteql`, `netsuite_get_record`, `netsuite_list_records`, `netsuite_record_metadata`, `netsuite_get_file`, `netsuite_get_vendor_bill_pdf` (read), plus owner-only writes `netsuite_create_vendor`, `netsuite_create_credit_memo`, `netsuite_set_invoice_dunning_hold`, `netsuite_update_instance_config` — read-only SuiteQL/record/metadata/File-Cabinet access across your connected NetSuite accounts, and on connections you own: create vendors, create customer credit memos, put invoices into dunning hold, and store per-instance AI context / guardrails the agent reads before writing | | `crm` | `crm_list_workspaces`, `crm_list_contacts`, `crm_get_contact`, `crm_create_contact`, `crm_update_contact`, `crm_list_companies`, `crm_create_company`, `crm_update_company`, `crm_add_activity`, `crm_list_templates`, `crm_create_template`, `crm_update_template`, `crm_list_campaigns`, `crm_get_campaign`, `crm_create_campaign`, `crm_add_call_task`, `crm_list_call_tasks` — research and populate a light CRM: contacts, companies, timeline activities, email templates, draft campaigns and the daily call list | | `salesforce` | `salesforce_list_instances`, `salesforce_soql`, `salesforce_soql_more`, `salesforce_tooling_soql`, `salesforce_search`, `salesforce_describe_global`, `salesforce_describe`, `salesforce_get_record`, `salesforce_slippage_report`, `salesforce_list_files`, `salesforce_download_file`, `salesforce_list_flows`, `salesforce_get_flow`, `salesforce_list_layouts`, `salesforce_get_layout`, `salesforce_list_flexipages`, `salesforce_get_flexipage`, `salesforce_list_applications`, `salesforce_get_application`, `salesforce_update_instance_config` (reads/config), plus the owner-only, per-connection-TOGGLED writes `salesforce_save_flow`, `salesforce_patch_flow`, `salesforce_activate_flow` (flows), `salesforce_create_record`, `salesforce_update_record`, `salesforce_delete_record` (records), `salesforce_save_field`, `salesforce_create_object`, `salesforce_set_field_permissions` (fields), `salesforce_save_layout`, `salesforce_patch_layout`, `salesforce_save_flexipage`, `salesforce_patch_flexipage` (layouts), `salesforce_deploy_metadata` (metadata; `apex` for ApexClass/ApexTrigger), plus `salesforce_deploy_status` (owner-only, no toggle — check a deploy by its `request_id`) — SOQL/SOSL queries, object metadata, single-record reads, file list + download, the Slippage Report, and Flow/Layout/Lightning-page read AND (where enabled) write access across your connected Salesforce orgs. Every `salesforce_list_instances` entry carries `instance_context` (account facts) + `instance_dont` (hard guardrails) — read both before acting — plus `writes` `{ flows, records, fields, layouts, metadata, apex }`: the per-connection write toggles the OWNER switches in the dashboard "Write Access" tab (flows on by default, everything else off). `apex` is deliberately separate from `metadata` — it deploys executable code. A disabled feature's write tools refuse with a pointer to the dashboard. | | `geo` | `geo_list_projects`, `geo_list_prompts`, `geo_get_project_report`, `geo_run_project` — list GEO Tracker projects, read mention-rate / share-of-voice / citation reports, and trigger manual runs against AI search engines (ChatGPT, Claude, Gemini, Perplexity, Google AI Overview) | | `tech` | `tech_lookup`, `tech_find_sites`, `tech_trends` — BuiltWith-backed tech-stack lookup for a domain, list of sites using a given technology, and adoption-coverage stats. Heavily cached (30d for lookups, 7d for site lists, 24h for trends) so repeated calls stay cheap upstream while users still pay full sticker price per call | | `personio` | `personio_list_instances`, `personio_list_employees`, `personio_get_employee`, `personio_list_custom_attributes`, `personio_list_time_offs`, `personio_list_time_off_types`, `personio_list_attendances`, `personio_absence_report`, `personio_list_job_positions`, `personio_list_applications`, `personio_get_application`, `personio_pipeline_funnel` — read-only HR + recruiting access. Sensitive HR fields (salary, IBAN, BIC, tax_id, social_security_number, date_of_birth, private_address, private_phone, private_email) are **always** redacted to `"__REDACTED__"` in MCP responses regardless of any caller setting. Plus `personio_update_instance_config` (any workspace member) — every `personio_list_instances` entry carries `instance_context` (facts) + `instance_dont` (guardrails); read both before acting. | | `browser` | **Cloud Browser** — `browser_create_session`, `browser_list_sessions`, `browser_navigate`, `browser_get_dom`, `browser_get_console`, `browser_handle_dialog`, `browser_screenshot`, `browser_scroll`, `browser_click`, `browser_drag`, `browser_long_press`, `browser_type`, `browser_select_option`, `browser_press_key`, `browser_run_actions`, `browser_set_viewport`, `browser_list_tabs`, `browser_switch_tab`, `browser_new_tab`, `browser_close_tab`, `browser_fill_credentials`, `browser_fill_credential_field`, `browser_fill_totp`, `browser_scan_totp_qr`, `browser_set_cookies`, `browser_clear_site_data`, `browser_inspect_storage`, `browser_upload_file`, `browser_download_file`, `browser_save_credentials`, `browser_list_credentials`, `browser_delete_credentials`, `browser_release_session` — drive a server-side Chromium (personal — isolated per user) on sites that have no API. Get past login walls with `browser_fill_credentials` (fills a saved login server-side — you never see the password) or, for multi-step / custom login forms it can't auto-detect, `browser_fill_credential_field` (put one saved value into a field you clicked); clear a 2FA step with `browser_fill_totp` when the entry has an authenticator seed saved; manage the saved-login wallet with the `*_credentials` tools (saving passes the password through your context); the user can also watch LIVE and TAKE OVER (mouse/keyboard) in the dashboard. Control modes agent/hybrid/human. Sessions cost tokens; logins persist between sessions via encrypted profiles. | | `gmail` | `gmail_list_accounts`, `gmail_search`, `gmail_get_message`, `gmail_get_thread`, `gmail_get_attachment`, `gmail_send`, `gmail_create_draft`, `gmail_list_drafts`, `gmail_send_draft`, `gmail_delete_draft`, `gmail_modify_labels`, `gmail_trash_message`, `gmail_untrash_message`, `gmail_delete_message`, `gmail_list_labels`, `gmail_create_label`, `gmail_delete_label`, `gmail_get_vacation`, `gmail_set_vacation`, `gmail_list_filters`, `gmail_create_filter`, `gmail_delete_filter`, `gmail_list_history` — full read+write access to your connected Gmail accounts (messages, threads, attachments, sending, drafts, labels, filters, vacation responder, incremental history). Accounts are strictly PERSONAL — never shared with other Lynk users. Search uses Gmail's own query syntax (`from:`, `subject:`, `has:attachment`, `is:unread`, `newer_than:7d`). `gmail_send` / `gmail_send_draft` deliver immediately and are NOT reversible — confirm recipient + content with the user first; prefer `gmail_create_draft` when unsure. `gmail_delete_message` is permanent (bypasses Trash) — prefer `gmail_trash_message`. Plus `gmail_update_account_config` — every `gmail_list_accounts` entry carries `instance_context` (mailbox facts) + `instance_dont` (guardrails); read both before sending/deleting. | | `teams` | `teams_list_accounts`, `teams_update_account_config`, `teams_list_chats`, `teams_get_messages`, `teams_search_messages`, `teams_send_message` — read, search and send Microsoft Teams CHAT messages (1:1 + group) as the connected user. Accounts are strictly PERSONAL — never shared, because every message is posted AS that person (Microsoft Graph has no app-only permission that can send a normal Teams message, so there is no bot identity available). `teams_search_messages` is the cheap entry point and accepts KQL scope terms (`from:bob`, `sent>2026-09-01`, `IsMentioned:true`, `hasAttachment:true`); it returns a relevance snippet, not full bodies — follow up with `teams_get_messages` on the hit's `chat_id`. `teams_send_message` delivers immediately and is NOT reversible — confirm the exact text and the recipient with the user first. v1 covers CHATS only, not team channels. Every `teams_list_accounts` entry carries `instance_context` (facts) + `instance_dont` (guardrails) — read both before sending. | | `mailbox` | `mailbox_list_accounts`, `mailbox_update_account_config`, `mailbox_list_folders`, `mailbox_search`, `mailbox_get_message`, `mailbox_get_attachment`, `mailbox_send`, `mailbox_create_draft`, `mailbox_forward_message`, `mailbox_modify`, `mailbox_move_message`, `mailbox_trash_message` — ONE generic tool family for EVERY connected mail account: IMAP/SMTP mailboxes, Microsoft 365 accounts AND Gmail accounts (bridged — the `gmail_*` tools keep working in parallel). Accounts are strictly PERSONAL. Account ids are strings; each `mailbox_list_accounts` entry carries its `provider` + `search_syntax` (query semantics are provider-NATIVE: Gmail operators vs Graph $search vs plain-text IMAP keyword) plus `instance_context`/`instance_dont` — read all of them before searching, sending or deleting. `mailbox_send` delivers immediately and is NOT reversible — confirm recipient + content with the user first; prefer `mailbox_create_draft` when unsure. To pass an existing mail on, use `mailbox_forward_message` rather than `mailbox_get_attachment` + `mailbox_send` — it moves the attachment bytes server-side, so they never travel through the agent context. `mailbox_trash_message` moves to Trash where one exists; on IMAP servers WITHOUT a trash folder it expunges (destructive — confirm first). Message ids are opaque per-account tokens and may CHANGE after `mailbox_move_message` (use the returned id). | | `calendar` | `calendar_list_accounts`, `calendar_list_calendars`, `calendar_list_events`, `calendar_get_event`, `calendar_create_event`, `calendar_update_event`, `calendar_delete_event` — read **and write** the calendars behind a connected Microsoft 365 or Google (Gmail) mail account. Calendar is a **capability of a mail account**, not a separate connection: the same account id, the same encrypted refresh token. It is only usable once the user re-consents with calendar scopes — `calendar_list_accounts` reports `calendar_enabled` per account and a `connect_url` for the ones missing it, so check that BEFORE calling anything else. Every event carries `join_url` + `join_source` (`native` = published by the platform, `body` = extracted from the invitation text — treat a `body` link as best-effort) and `conference` (teams | google_meet | zoom | …), which is what makes an auto-joining meeting bot possible. Writes **notify the attendees immediately** and are not silently reversible: creating or updating with `attendees` sends real invitations, `attendees` REPLACES the whole list, and `calendar_delete_event` cancels the meeting for everyone — confirm with the user first. IMAP/SMTP mailboxes have no calendar. Accounts are strictly PERSONAL. | | `canvas` | `canvas_publish`, `canvas_update`, `canvas_list`, `canvas_get`, `canvas_delete`, `canvas_list_folders`, `canvas_create_folder`, `canvas_update_folder`, `canvas_upload_asset`, `canvas_list_assets`, `canvas_delete_asset`, `canvas_kv_get`, `canvas_kv_set`, `canvas_kv_delete` — publish a single self-contained HTML document (or a `markdown` document that Lynk renders to a styled page) and get a public `https://lynk.run/canvas/` link (optional password, expiry, and memorable `slug` short URL; for a large/local document publish from a URL via `source_url` or curl it to a presigned upload URL), edit it in place (keeps the same link + data), organize pages into folders that carry a shared access policy the pages inherit as a floor, upload images/CSS/JS/fonts into a folder and reference them from its pages (a folder = a small multi-file website), list/fetch/delete pages, and read/write each page's per-page key-value mini-DB. Pages render in a sandboxed (opaque) origin. Publishing/content-updates bill `CANVAS_TOKENS_PER_PUBLISH` (2) tokens; unlimited-plan + admin users are not charged. The mini-DB is public read+write (anyone with the link can write — for counters/guestbooks/shared state, never secrets). | | `voice` | `voice_tts`, `voice_sound_effect`, `voice_list_voices`, `voice_request` — ElevenLabs text-to-speech + sound-effect generation. **BYOK**: runs against the USER's OWN connected ElevenLabs key — the user pays ElevenLabs directly and Lynk charges NO tokens; if no key is connected the tool errors and the user connects one at `https://api.lynk.run/voice`. Returns a downloadable audio URL (a public `https://lynk.run/dl/` shared file, or a stable bucket object via `store_to`) — MCP can't hand back raw audio bytes. | | `github` | `github_list_accounts`, `github_update_account_config`, `github_list_repos`, `github_create_repo`, `github_list_environments`, `github_list_secrets`, `github_set_secret`, `github_delete_secret`, `github_list_variables`, `github_set_variable`, `github_delete_variable` — GitHub Actions **secret + variable management** plus **repository creation** on the user's connected GitHub accounts (Personal Access Tokens, stored encrypted in Lynk). `github_set_secret` seals the value SERVER-SIDE with the repo/environment public key (libsodium sealed box — GitHub's required encryption), so callers pass plaintext and never touch the crypto; the value is never stored by Lynk and is redacted from the audit log. Secrets are write-only end-to-end (GitHub cannot return them) — an overwrite is irrecoverable, so check `github_list_secrets` + confirm with the user first. Variables are PLAINTEXT config (readable back) — never put anything sensitive in one. Repo + environment scoping via `repo: "owner/repo"` + optional `environment`. `github_create_repo` creates a new repository (PRIVATE by default; needs the classic `repo` scope or fine-grained Administration:write on all repositories). Accounts are strictly PERSONAL. No Lynk tokens charged. | | `ssh` | `ssh_list_connections`, `ssh_run`, `ssh_upload`, `ssh_download`, `ssh_update_connection_config` — run shell commands + transfer files over SSH on servers the user registered as connections (and connections shared with them). One-shot execution — shell state does NOT persist across calls. Every command is audit-logged. Connections carry `instance_context` (host facts) + `instance_dont` (hard guardrails) — read both before acting. Connections the owner marked read-only reject obviously-destructive commands + anything off their allowlist. No Lynk tokens charged (the user brings their own servers). | | `brain` | `brain_search`, `brain_get_note`, `brain_list_notes`, `brain_create_note`, `brain_update_note`, `brain_delete_note`, `brain_graph`, `brain_list_tags` — the workspace **Brain**: a standalone Obsidian-style team knowledge base of interlinked markdown notes (`[[wikilinks]]`, backlinks, tags, FTS5 search, graph). Workspace-scoped (omit `workspace_id` for your personal workspace); any workspace member reads + writes. No tokens charged. | | `phone` | `phone_list_trunks`, `phone_call`, `phone_say`, `phone_get_call`, `phone_list_calls`, `phone_hangup` — **Lynk Phone**: place and drive REAL outbound phone calls over the workspace's own SIP carrier, speak on a live call (TTS), read the live transcript, hang up. Workspace-scoped via `workspace_members`. **`phone_call` rings an actual human and costs real money on the customer's carrier** — always confirm the destination number with the user first and never dial to "test" the tool. Two modes: a plain call you drive with `phone_say`, or a **managed agent** (pass `agent_system_prompt`) where Lynk runs the whole speech→LLM→speech loop autonomously. Billed in Lynk tokens per call minute / utterance / agent turn. | | `caya` | `caya_list_instances`, `caya_list_folders`, `caya_list_documents`, `caya_download_document`, `caya_move`, `caya_trash`, `caya_mark_read`, `caya_mark_unread`, `caya_tag`, `caya_create_folder`, `caya_rename_folder` — read + organise the user's connected **Caya** digital mailroom (scanned physical post). List folders (inbox/archive/trash + sub-folders) and documents, download a document PDF (base64, returned inline — never a public link, since Caya holds sensitive personal mail), and SORT mail: move/trash items, mark read/unread, tag, and create/rename folders. Connections are strictly PERSONAL — never shared with other Lynk users. No Lynk tokens charged (the user brings their own Caya account). | | `netbox` | `netbox_list_instances`, `netbox_search`, `netbox_query`, `netbox_get`, `netbox_schema`, `netbox_changelog`, `netbox_update_instance_config` — **READ-ONLY** access to connected **NetBox** instances (DCIM/IPAM source of truth): devices, racks, sites, interfaces, cables, IP addresses, prefixes, VLANs, VRFs, virtual machines, circuits, tenants, the object change log, and — where the netbox-inventory plugin is installed — hardware **assets, suppliers, purchases and deliveries**. Workspace-scoped via `workspace_members`. Cannot create, change or delete anything in NetBox. No Lynk tokens charged (the user brings their own NetBox token). | | `snipeit` | `snipeit_list_instances`, `snipeit_find_asset`, `snipeit_list`, `snipeit_get`, `snipeit_user_items`, `snipeit_activity`, `snipeit_update_instance_config` — **READ-ONLY** access to connected **Snipe-IT** asset registers: hardware (by asset tag, serial or text), everything checked out to a person, license seats, accessories, consumables, components, locations, models and the activity log. Workspace-scoped via `workspace_members`. Cannot check out, check in, create, change or delete anything. No Lynk tokens charged (the user brings their own Snipe-IT token). | | `grafana` | `grafana_list_instances`, `grafana_search_dashboards`, `grafana_get_dashboard`, `grafana_list_datasources`, `grafana_query`, `grafana_list_alerts`, `grafana_list_folders`, `grafana_update_instance_config` — **READ-ONLY** access to connected **Grafana** instances: dashboards **including the query each panel runs**, datasources, folders, metric queries (PromQL + SELECT-only SQL) and what is currently alerting. Workspace-scoped via `workspace_members`. Cannot create or change dashboards, alert rules or any other Grafana object. No Lynk tokens charged (the user brings their own Grafana service-account token). | | `elastic` | `elastic_list_instances`, `elastic_list_indices`, `elastic_field_caps`, `elastic_list_data_views`, `elastic_esql`, `elastic_search`, `elastic_get_document`, `elastic_list_saved_objects`, `elastic_list_alerts`, `elastic_cluster_health`, `elastic_update_instance_config` — **READ-ONLY** access to connected **Elasticsearch** clusters (+ optional Kibana): ES|QL and Query-DSL searches over the indices the connection is scoped to, index and data-stream discovery, field schemas, plus Kibana data views, saved objects and alerting rules. Workspace-scoped via `workspace_members`. Cannot index, update, delete or reindex anything, and system indices (anything starting with `.`) are unreachable — the security index holds API-key hashes. No Lynk tokens charged (the user brings their own Elasticsearch credential). | Scopes are requested at consent time. Granted scopes are baked into the access token and enforced server-side: tools whose scope is not granted are not registered on the server instance. ## Pricing — MCP costs the same as REST **An action costs the same whichever surface it arrives on.** `web_search` over MCP is billed exactly like `POST /search/v1/web`; `tech_lookup` over MCP is billed exactly like the REST lookup, per domain. The surface is recorded on the ledger entry, it does not change the price. This was not always true: nine lookup tools (`web_search`, `intel_lookup`, `domain_check`, `tech_*`, `scrape_*`) used to be free over MCP while the identical REST call was billed. They now charge, with the same **unit** as REST — so a `num=200` search costs 20 tokens on both, not 20 on one and 1 on the other. What that means for an agent: - The per-tool pricing notes below are authoritative for MCP too. Where a tool says "ask the user before raising `pages` / `num`", that guidance now has a real cost behind it. - Multi-unit calls scale: pay for what you ask for, get refunded what the upstream couldn't deliver (an early-exit search or a crawl that ran out of pages settles down automatically). - A failed call is refunded in full. - `estimate_only` / catalog tools (`domain_tlds`, `GET /tech/v1/tags`) remain free — they check nothing. - Unlimited-plan and admin accounts are never charged, on any surface. Insufficient balance surfaces as a tool error naming the cost and your balance, not a silent failure. Live prices per action are visible to the workspace admin at `https://api.lynk.run/admin/?tab=endpoints`. ## Tools reference ### `intel_lookup` Input: `{ target: string, mode?: 'lite' | 'medium' | 'full' }`. Default mode is `lite`. Modes: `lite` (local MMDB + DNS, ~10-50 ms) returns a **compact, consolidated** result — a single best `asn`/`org`/`country`/`country_name`/`city`/`region` merged across all providers, plus (domains only) `mail_provider` + `nameservers` + a `hosting`/`cloud_provider` flag. Small enough to fan out across hundreds of targets for bulk enrichment / market research. `medium` (+ rDNS/WHOIS/SSL, no DNSBL, ~200-800 ms) and `full` (everything incl. 73 IP RBLs + 8 domain RHSBLs, ~1-3 s) return the **full rich object** (per-provider blocks, DNS TXT, WHOIS, SSL). **In medium/full a `null` field means "not checked in this mode", NOT "checked and clean"** — use `full` before answering blacklist/reputation questions. ### `bgp_company_search` Input: `{ query: string, limit?: number, include_relationships?: ('upstreams'|'peers'|'customers')[] }`. Returns array of `{ asn, name, org, domain, country, prefixes[], prefix_count, total_ips, relationships: { upstreams, peers, customers } }`. Pass `include_relationships` to also get the actual ASN identities for the chosen types — each matched ASN then carries `relationship_names: { upstreams?[], peers?[], customers?[], truncated? }` (only the requested keys present) where each entry is `{ asn, name, org, domain, country }`. upstreams = transit providers ("who does this company buy transit from?"), customers = downstream networks, peers = lateral. Deduped, capped at 100 per type. Omit = counts only; narrow the types (e.g. just `["upstreams"]`) for large carriers with many downstreams. Free, no key needed in the underlying data sources (CAIDA + iptoasn). ### `domain_check` Input: `{ name?: string, tlds?: string[] | "all", domains?: string[], variations?: boolean, estimate_only?: boolean, async?: boolean, no_cache?: boolean }`. Pass `name` (a bare label, e.g. `mycoolstartup`) to fan out across `tlds`, and/or `domains` for explicit full domains. `tlds` defaults to `com, net, org, io, ai, app, dev, co, me, xyz, sh`; pass the literal string `"all"` for the full 40-ending catalog (see `domain_tlds`). Set `variations: true` to also fan the bare `name` across a curated set of startup affixes — prefixes `get, try, use, go, my, join, the, hey, just, with` + suffixes `app, hq, hub, ly, now, 24, labs, ai, io, ify, one, os, kit, flow` (so `acme` also yields `getacme`, `justacme`, `acmehq`, `acmeify`, … — **25 names per base**). Subdomains are reduced to the registrable domain (eTLD+1). Max 5000 domains per call. **Size and runtime — read this before a big sweep.** The candidate count multiplies: `variations` alone is 25 names, and 25 × the full TLD catalog is **1000 domains**. Runtime is driven by how many endings answer slowly, not by the domain count — a cached or free name resolves in milliseconds, while a registry that blocks us costs seconds and returns `unknown`. Measured against production: 50 cold domains take ~2s when most are free, ~22s when many are blocked. - `estimate_only: true` returns `{ candidate_count, estimated_seconds: { fast, typical, slow }, runs_async, exceeds_limit }` and **checks nothing** — free, no tokens. Use it to tell the user what a sweep will cost before running it. - **Above 200 candidates the tool does not block.** It returns `{ mode: "job", job_id, total, estimated_seconds, … }` immediately; poll `domain_check_status` until `status` is `"completed"`. `async: true` forces that path below the threshold. Below it you get `{ mode: "sync", summary, results }` as before. - **Ask the user before launching a sweep above 200 candidates — unless they already asked for a broad search** ("check all TLDs", "every variation", "full sweep"). If they did, just run it. Returns (sync mode) `{ mode: "sync", summary: { total, available, taken, unknown, for_sale, parked }, invalid[], results[] }`; each result is `{ domain, tld, status, listing, price, buy_url?, method, reason, checked_at }`, where `method` is one of `dns | rdap | whois | whoapi | none`. Tiered cascade per domain: **DNS** (NS records ⇒ `taken`, ~tens of ms) → **RDAP** (HTTP 404 ⇒ `available`, authoritative) → **port-43 WHOIS** pattern match for TLDs without RDAP → optional **WhoAPI** third-party fallback (only when the admin has configured a key, and only when tiers 1–3 all returned `unknown` — covers registries that block our IP, e.g. `.es`, or rate-limit us heavily, e.g. `.uk`, `.shop`). **`status: 'unknown'` means no source could decide (registry blocked us, exotic TLD) — it does NOT mean available.** **Aftermarket:** on a `taken` domain, `listing` refines the verdict — `'for_sale'` (listed on a domain marketplace / sales lander detected), `'parked'` (a parking page was detected — often, but not provably, for sale), or `null` (regular website / no signal). A `for_sale` result may carry `price` (`{ amount, currency }`) — the buy-now asking price where the marketplace publishes one; `price: null` on a for_sale listing means "Price on Request" — plus `buy_url`, the purchase/click target. Nameserver-based for_sale/parked detection runs for every domain; HTTP-based enrichment (lander visit + price extraction) runs for the first 50 taken domains per call. `taken` results (incl. their listing/price) are cached 24 h, `available` results 10 min. ### `domain_check_status` Input: `{ job_id: string, include_results?: boolean }`. Polls a background sweep started by `domain_check` in `mode: "job"`. Returns `{ job_id, status, total, completed, progress_pct, estimated_seconds_remaining?, summary?, invalid?, error? }`. `status` is `running | completed | failed`. Pass `include_results: true` on the FINAL poll to also get every per-domain record — omit it on progress ticks, since a 1000-domain sweep carries that many records. While running, wait roughly `estimated_seconds_remaining` between polls instead of hammering. Jobs (and their results) are kept for **24 hours**. ### `domain_tlds` No input. Returns `{ default[], all[], count, note }` — the curated default endings used when `tlds` is omitted, and the full catalog that `tlds: "all"` expands to. Call it when the user asks for "all TLDs" or names an ending you're not sure is covered, instead of hardcoding a list. Free, no tokens. ### `web_search` Input: `{ q: string, gl?: string, hl?: string, num?: number, format?: 'json' | 'markdown' }`. Runs a Google web search via serper.dev and returns organic results plus answer box / knowledge graph / "people also ask" / related searches when present. **Pricing — read carefully:** `1 token per 10 results requested`, rounded up. `num=10` (default) costs 1 token; `num=30` costs 3 tokens; `num=100` costs 10; `num=200` (max) costs up to 20 tokens. The gateway handles Google's 10-per-page reality internally by fetching multiple serper pages and stitching them — that's why num scales linearly with cost. Early-exit on sparse queries refunds unused pages automatically (Google empty after page 3 of a num=50 request → user pays 3, not 5). **⚠️ AGENT INSTRUCTIONS:** Do NOT silently escalate `num` above the default of 10. The default answers most research questions for 1 token. Before requesting more than 10 results, **ask the user first** whether they want to spend the extra tokens. Only escalate when the top 10 were insufficient AND the user explicitly approved. Defaults: `gl=de`, `hl=de`, `num=10`. Max `num=200`. Pass `format='markdown'` to get an LLM-friendly rendered document instead of JSON — recommended when feeding the result straight back into an LLM context window. Authenticated calls bypass per-minute rate limits; unauth callers are limited to 20 / min / IP. JSON shape: `{ query, gl, hl, num, requested, fetched_at, organic[], answer_box?, knowledge_graph?, people_also_ask?, related_searches? }` — `num` is what we actually returned (may be lower than `requested` if Google ran out). **Optional sections (`answer_box`, `knowledge_graph`, `people_also_ask`, `related_searches`) are absent when Google doesn't return them — don't assume they exist.** ### `scrape_page` Input: `{ url: string, modes?: Array<'markdown' | 'html' | 'screenshot' | 'pdf' | 'links' | 'images' | 'branding'>, ...options }`. Pass one or more modes to capture several formats in one call; default is `['markdown']` (best for LLM context). The `images` mode returns `[{ src, alt?, width?, height? }]`. The `branding` mode runs a browser-side evaluator (borrowed from dembrandt, MIT) inside the existing Crawl4AI Playwright session and returns a Brand-DNA envelope: `{ siteName, colorScheme, logo: { url, type:'wordmark'|'logomark'|'combination', source:'img'|'svg'|'css-background', reversed, background, width, height, alt }, logoInstances[], favicons[] (incl. PWA manifest icons + og:image + twitter:image + apple-touch-icon), colors: { primary, secondary, accent, background, textPrimary, textSecondary }, palette[{ normalized, count, confidence, sources }], cssVariables, typography: { fontFamilies, fontSizes, fontWeights, sources: { googleFonts[], adobeFonts, variableFonts[] }, styles[] } }`. Cached 1 h per `(url, modes, options)`. Authenticated calls bypass per-minute rate limit and bill via tokens. **Optional Firecrawl-style options block** (omit for defaults; same shape on `scrape_crawl_start`): - `excluded_tags: string[]` — HTML tags to strip (e.g. `['nav','footer','aside']`). - `include_selector: string` — CSS selector that scopes extraction to a single element (e.g. `'main article'`). - `wait_ms: number` — Delay after page-load before reading HTML, for JS-hydrated sites. Cap 30000. - `timeout_ms: number` — Hard page-load timeout. Cap 120000. - `main_content_only: boolean` — Drop nav/footer/aside/header/forms + short blocks (readability filter). - `screenshot_full_page: boolean` — Full-page screenshot instead of viewport-only. Only meaningful with the `screenshot` mode. - `max_age_ms: number` — Per-request cache TTL override. Pass `0` to force a fresh scrape; otherwise the smaller of this value and the global 1 h default wins. - `html_raw: boolean` — Treat the raw `html` field as primary instead of `cleaned_html` (both are always present in the response). - `parse_pdf: boolean` — When the URL points at a PDF, parse it via Crawl4AI's PDF strategy instead of rendering in the browser. Best-effort — falls back with a 502 if the sidecar build doesn't ship the strategy. - `enhanced_mode: boolean` — Anti-bot tarning (Crawl4AI `magic`: simulate_user + override_navigator + random UA). Slower per page, helps with light bot-protection. NOT a captcha solver. ### `scrape_crawl_start` + `scrape_job_status` Multi-page crawls run asynchronously. `scrape_crawl_start` returns a `job_id` immediately; poll with `scrape_job_status({ job_id })` until `status === 'completed'`. Strategies: `bfs` (default), `dfs`, `best_first`. `modes` accepts the same multi-select array as `scrape_page` (including `images`). The same options block as `scrape_page` is accepted and applied to every page in the crawl. Caps: max 250 pages, max depth 4. ### `scrape_extract` Input: `{ url: string, prompt: string }`. The Lynk gateway uses an admin-configured LLM provider to extract structured data; returns 503 (`Upstream scraper unavailable` or similar) if no provider is configured. ### `files_list` / `files_delete` / `files_upload` List, delete and upload files via Lynk Files. `files_list` / `files_delete`: admins see all files, regular users see only their own. `files_upload({ file_name, content_base64? | source_url?, password?, expires_in_days? })` stores a file and returns `{ id, url, size, expires_at, has_password }` — `url` is the public `https://lynk.run/dl/` download link (gated by `password` if set, auto-expiring after `expires_in_days` 1-365 if set, else evergreen). Provide the bytes ONE of THREE ways: (1) `source_url` (a public http(s) URL Lynk fetches server-side, SSRF-guarded, no redirects followed, ≤250 MB); (2) `content_base64` (inline, ≤15 MB); or (3) NEITHER — call with just `file_name` (+ optional `password`/`expires_in_days`) and the tool returns `{ mode:"upload_url", upload_url, method:"PUT", field:"file", expires_at, instructions }`. The `upload_url` is a short-lived (~30 min) presigned link; the user (or any process) PUTs the raw bytes to it with NO auth header (`curl -X PUT -F "file=@local.apk" ""`) — the URL is the credential. Mode (3) is the path for a LARGE local file that has no public URL and is too big to base64 inline (the bytes never transit the LLM tool call). Per-user shared-file storage quota: 500 MB total (buckets excluded; over quota → HTTP 413). No tokens charged. The tool does NOT email the link — share the returned `url` yourself. ### `bucket_*` — per-user object store A bucket is a private, owner-only named container of objects addressed by `(bucket, key)`. Unlike shared files there is no public link — it is an authenticated object store giving a STABLE address so a CI run (or any bulk transfer) can upload once and fetch the same key deterministically on every later run, with no opaque file id to persist. Caps: 50 buckets/user, 1000 objects/bucket, 10 MB/object. - `bucket_list()` → `[{ id, name, created_at }]`. - `bucket_create({ name })` → `{ id, name, created_at, created }`. Idempotent — returns the existing bucket if present (safe to call at the top of every run). Names: lowercase a-z, 0-9, hyphens, 1-64 chars. - `bucket_delete({ name })` → `{ ok, name }`. Deletes the bucket AND all its objects. Irreversible. - `bucket_list_objects({ bucket, prefix? })` → `[{ key, size, mime_type, created_at }]`. Optional key-prefix filter (e.g. `prefix: "certs/"`). - `bucket_put_object({ bucket, key, content_base64? | source_url? })` → `{ ok, key, size }`. UPSERT-by-key (re-uploading a key overwrites it). Keys are slash-separated path segments (letters, digits, `. _ - + @ ( )` per segment), e.g. `"certs/distribution.p12"`. Same base64-or-source_url choice as `files_upload`; ≤10 MB/object. - `bucket_get_object({ bucket, key })` → `{ key, size, mime_type, content_base64 }`. Bytes are base64-encoded in the response. - `bucket_delete_object({ bucket, key })` → `{ ok, key }`. ### `salesforce_list_instances` Lists the Salesforce orgs the user has connected. Returns `{ id, name, login_url, api_version, last_test_ok, instance_context, instance_dont, writes: { flows, records, fields, layouts, metadata, apex }, ... }`. `writes` shows which WRITE features the connection owner enabled in the dashboard "Write Access" tab — a disabled feature's write tools refuse until it's switched on (flows defaults on; records/fields/layouts/metadata/apex default off). Every other `salesforce_*` tool needs an `instance_id` from this list. ### `salesforce_soql` + `salesforce_soql_more` Input: `{ instance_id: number, soql: string }`. Runs a **read-only** SOQL `SELECT` (no DML — non-SELECT input is rejected). A default `LIMIT` is appended when the query has none and is not an aggregate. Returns `{ totalSize, done, records, nextRecordsUrl? }`. When `done` is false, call `salesforce_soql_more({ instance_id, next_records_url })` with the locator to page through results. ### `salesforce_tooling_soql` Input: `{ instance_id: number, soql: string }`. Runs a **read-only** SOQL `SELECT` against the Salesforce **Tooling API** — the metadata objects the normal Data API (and therefore `salesforce_soql`) cannot see: `ValidationRule`, `ApexClass`, `ApexTrigger`, `WorkflowRule`, `EntityDefinition`, `FieldDefinition`, `CustomField`, `DuplicateRule`, `Layout`, `Flow`, … Returns the same `{ totalSize, done, records, nextRecordsUrl? }` shape. **When to reach for it:** `salesforce_soql` failing with `sObject type 'X' is not supported` means X is a Tooling object, NOT that it is missing — re-run the identical query here. **Metadata is one record at a time.** The `Metadata` and `FullName` fields carry the real definition (a validation rule's `errorConditionFormula`, an Apex class's `Body`, …) and Salesforce only allows them when the query matches a SINGLE row. So it's a two-step read: 1. `SELECT Id, ValidationName, Active, Description, ErrorMessage, ErrorDisplayField FROM ValidationRule WHERE EntityDefinition.QualifiedApiName = 'Contract'` 2. per rule: `SELECT Id, FullName, Metadata FROM ValidationRule WHERE Id = '03d…'` Selecting `Metadata` over a multi-row filter fails with an implementation-restriction error. Same rule for `ApexClass.Metadata`, `Flow.Metadata`, `Layout.Metadata`. Also handy: `SELECT QualifiedApiName, DataType, IsCalculated FROM FieldDefinition WHERE EntityDefinition.QualifiedApiName = 'Contract'` — `IsCalculated` tells you reliably whether a field is a formula (a describe-based guess is not authoritative). ### `salesforce_search` Input: `{ instance_id: number, sosl: string }`. Runs a read-only SOSL `FIND` text search across objects, e.g. `FIND {Acme} IN ALL FIELDS RETURNING Account(Id, Name)`. Returns `{ searchRecords }`. ### `salesforce_describe_global` + `salesforce_describe` `salesforce_describe_global({ instance_id })` lists every sObject (`name`, `label`, `custom`, `queryable`, `keyPrefix`). `salesforce_describe({ instance_id, sobject })` returns one object's fields (name, label, type, picklist values, references) — use it to write correct SOQL. ### `salesforce_get_record` Input: `{ instance_id, sobject, record_id, fields? }`. Reads one record by 15/18-char id. Read-only. ### `salesforce_slippage_report` Input: `{ instance_id, period: 'month' | 'quarter', anchor: string }`. Computes the slippage report for a given calendar month or quarter. `anchor` format: `'YYYY-MM'` for `period='month'` (e.g. `'2026-05'`), `'YYYY-Q[1-4]'` for `period='quarter'` (e.g. `'2026-Q2'`). A slipped opportunity is one whose `CloseDate` at the START of the period was inside the period but is now scheduled AFTER the period end, and is not Closed-Won. Reconstructed live from `OpportunityFieldHistory` — **requires "Set History Tracking" enabled on `Opportunity.CloseDate` in the Salesforce org**, otherwise the report returns a warning and zero slips. Returns `{ report: { period, outcome, slip_rate_pct, slip_value_rate_pct, chronic_slipper_count, aging_buckets, slipped: [...] , warnings }, dataset: { opp_count, history_count, refreshed_at, truncated } }`. Each slipped row carries the full `close_date_history` (every CloseDate change with `at`, `from`, `to`) so an agent can narrate why a deal slipped. Per-instance dataset cached 15 min; switching periods is instant. ### `salesforce_list_files` Input: `{ instance_id, record_id?, limit? }`. Lists files in the org — both modern Salesforce Files (`ContentDocument`/`ContentVersion`) and legacy `Attachment`s. With `record_id` (15/18-char), returns files linked to that record (both models); without it, the most recently created Files. Each row: `{ download_id, model: 'file' | 'attachment', content_document_id, title, file_extension, content_type, size, created_date }`. Pass `download_id` to `salesforce_download_file`. Read-only. ### `salesforce_download_file` Input: `{ instance_id, file_id }`. Downloads one file and returns it as base64: `{ download_id, file_name, content_type, size, content_base64 }`. `file_id` accepts a `ContentVersion` id (`068…`), a `ContentDocument` id (`069…` — auto-resolved to its latest version), a legacy `Attachment` id (`00P…`) or a `Document` id (`015…`) — typically the `download_id` from `salesforce_list_files`. Files larger than the 25 MB cap are refused. Read-only — no org-side setup required (unlike NetSuite, Salesforce's REST API serves blob bodies natively). ### `salesforce_list_flows` Input: `{ instance_id, limit? }`. Lists the org's Flows via the Tooling API — one entry per flow. Each: `{ definition_id (300…), developer_name, description, active_version_id (301…|null), latest_version_id (301…|null), active_version, latest_version }` where the version objects carry `{ Id, MasterLabel, VersionNumber, Status, ProcessType }`. Pass an `active_version_id`/`latest_version_id` to `salesforce_get_flow`, or the `definition_id` to `salesforce_activate_flow`. Read-only. ### `salesforce_get_flow` Input: `{ instance_id, flow_id }`. Returns one flow version's full definition, including the editable `Metadata` object + `FullName`. `flow_id` is a Flow version id (`301…`) or a FlowDefinition id (`300…`, resolved to its latest version). The `Metadata` object is what you edit and pass back to `salesforce_save_flow`. Can be large. Read-only. ### `salesforce_save_flow` Input: `{ instance_id, full_name, metadata }`. **OWNER-ONLY write.** Creates a NEW version of the flow named `full_name` from the full flow `metadata` object (get the current one via `salesforce_get_flow`, edit, pass back). Salesforce does NOT allow editing an active version in place — this ALWAYS creates a new, **INACTIVE** (Draft) version and leaves the live flow untouched until you call `salesforce_activate_flow`. Under the hood the connector deploys the `metadata` via the Salesforce **Metadata API** (a zip deploy — the Tooling API can't add a version to an existing flow) and forces the new version to Draft, so you can pass the `Metadata` from `salesforce_get_flow` back unchanged (or edited) and always get an inactive version; you do NOT need to touch `status`/`fullName` yourself. **For an EDIT to an existing flow prefer `salesforce_patch_flow`** — this tool needs the whole 10–15 KB definition and nothing catches a transcription slip. Pass `validate_only: true` to VALIDATE the metadata without saving anything: without it, an attempt that only proved the metadata malformed still leaves a throwaway Draft, overwriting the existing one. The deploy is async: the tool waits ~45s and then returns `{ status: "pending", request_id }` rather than hanging past the transport timeout — that is NOT a failure, poll `salesforce_deploy_status` and do NOT re-run the deploy. Returns `{ id (deployed Flow component id), success, status, request_id, errors }`. Requires the run-as user to have "Manage Flow" + "Modify Metadata Through Metadata API Functions" in Salesforce. SOQL permission check: on `PermissionSet`/`Profile` the columns are `PermissionsManageInteraction` (= Manage Flow — `PermissionsManageFlow` does not exist) + `PermissionsModifyMetadata`, joined through `PermissionSetAssignment`. Confirm with the user first; recommend reviewing the new version in Flow Builder before activating. ### `salesforce_activate_flow` Input: `{ instance_id, flow_definition_id, version_number }`. **OWNER-ONLY write (`writes.flows` toggle).** Sets which version of a flow is active in the live org; `version_number: 0` deactivates all versions. Changes PRODUCTION automation — confirm the exact flow + version first. Requires the run-as user to have "Manage Flow". Use `salesforce_list_flows` for the `flow_definition_id` (300…) and version numbers. ### `salesforce_create_record` / `salesforce_update_record` / `salesforce_delete_record` **OWNER-ONLY writes, gated by the connection's `writes.records` toggle.** Plain REST record DML — one record per call. `salesforce_create_record({ instance_id, sobject, fields })` → `{ id, success }`; `salesforce_update_record({ instance_id, sobject, record_id, fields })` changes only the passed fields (`Id`/`attributes` keys are stripped so queried records round-trip); `salesforce_delete_record({ instance_id, sobject, record_id })` sends the record to the Salesforce recycle bin (destructive — confirm the exact record with the user first; parent deletes may cascade to children). Use `salesforce_describe` for correct field API names/types; lookup fields take the related record's 15/18-char id. Writes run as the connection's run-as user against PRODUCTION data — `INSUFFICIENT_ACCESS` means that user lacks object/field permission. ### `salesforce_save_field` Input: `{ instance_id, sobject, field_name, metadata, validate_only? }`. **OWNER-ONLY write (`writes.fields` toggle).** Creates OR updates a CUSTOM field (`field_name` must end in `__c`) on a standard or custom object — one Metadata API deploy with upsert semantics. `metadata` is the CustomField definition without fullName, e.g. `{ "label": "Deal Score", "type": "Number", "precision": 3, "scale": 0 }`; Text needs `length`, Picklist needs `valueSet.valueSetDefinition.value[]`, Checkbox needs `defaultValue`, Lookup needs `referenceTo` + `relationshipName`. `validate_only: true` runs a validation deploy (checks everything, saves nothing). **CRITICAL: a freshly created field is invisible to every user until FLS is granted — call `salesforce_set_field_permissions` right after.** Requires "Customize Application" + "Modify Metadata Through Metadata API Functions" on the run-as user. ### `salesforce_create_object` Input: `{ instance_id, full_name, metadata, validate_only? }`. **OWNER-ONLY write (`writes.fields` toggle).** Creates a custom object (`full_name` ends in `__c`; updates are additive — never delete existing fields). Minimal metadata for a new object: `{ "label", "pluralLabel", "nameField": { "label", "type": "Text" }, "deploymentStatus": "Deployed", "sharingModel": "ReadWrite" }`. Add fields afterwards with `salesforce_save_field`. The object needs a tab + permissions in Setup before end users see it. ### `salesforce_set_field_permissions` Input: `{ instance_id, permission_set_id, sobject, field_name, read?, edit? }`. **OWNER-ONLY write (`writes.fields` toggle).** Grants or updates field-level security for one field on one permission set (query-first, create-or-update — safe to re-run). Defaults to read+edit. Find permission sets via SOQL: `SELECT Id, Label FROM PermissionSet WHERE IsOwnedByProfile = false`. The required follow-up after `salesforce_save_field`. ### `salesforce_list_applications` / `salesforce_get_application` `salesforce_list_applications({ instance_id, limit? })` lists the org's Lightning/Classic apps (Tooling API). Each row: `{ id, full_name, developer_name, label, namespace_prefix, deployable }`. **Use `full_name`** — it is what a deploy addresses the app by and is NOT the DeveloperName: an app with a namespace differs (`"standard__EasyMarketing"` has DeveloperName `"EasyMarketing"`), while a local app like `"Link11_Sales"` is the same either way. `deployable: false` marks an app from a MANAGED package, whose metadata cannot be changed. `salesforce_get_application({ instance_id, application })` takes the `02u…` id or the DeveloperName and returns the app's editable `Metadata` (`tabs` = the ordered nav, plus `label`, `brand`, `navType`/`uiType`, `formFactors`, `utilityBar`, `actionOverrides`, `profileActionOverrides`) together with its `FullName`. Read-only, not toggle-gated — but it is the REQUIRED first step before `salesforce_deploy_metadata` touches an app. ### `salesforce_list_layouts` / `salesforce_get_layout` `salesforce_list_layouts({ instance_id, sobject?, limit? })` lists classic page layouts (Tooling API; `sobject` filters to one object — custom objects are resolved automatically). `salesforce_get_layout({ instance_id, layout_id })` returns one layout's editable `Metadata` + `FullName` (e.g. `"Account-Account Layout"`). Read-only, not toggle-gated. ### `salesforce_save_layout` Input: `{ instance_id, full_name, metadata, validate_only? }`. **OWNER-ONLY write (`writes.layouts` toggle).** Deploys an edited classic page layout. **NO draft state — the deploy replaces the whole layout and is live immediately** for its assigned profiles. Always fetch the current definition via `salesforce_get_layout`, edit it, and prefer `validate_only: true` as a dry run. `full_name` must be passed back exactly as returned (layout names contain spaces / URL escapes). ### `salesforce_patch_layout` Input: `{ instance_id, layout_id, ops: [{ op, field?, section?, column?, after?, before?, behavior?, action?, action_type?, position? }], validate_only? }`. **OWNER-ONLY write (`writes.layouts` toggle).** Surgical edit of a classic page layout. Ops: `add_field` / `remove_field` / `move_field` / `set_behavior` (`Edit` | `Readonly` | `Required`) and `add_action` / `remove_action` (the "Salesforce Mobile and Lightning Experience Actions" bar; `action_type` QuickAction | StandardButton | CustomButton | ProductivityAction, optional 0-based `position`, sortOrder renumbered). Place fields with `after`/`before` another field or `section` label + 1-based `column` (appends). Field names are object-relative (`Region__c`). Server-side fetch → patch → verify that sections, columns, related lists, blank spaces, every other field + its behavior and the action set are unchanged apart from the addressed items → deploy via the same path as `salesforce_save_layout`. Any drift → refuses, deploys nothing. Addressing mistakes (duplicate add, missing field, unknown section/column, custom-links section) are errors. Live immediately; dry-run with `validate_only: true`. ### `salesforce_list_flexipages` / `salesforce_get_flexipage` `salesforce_list_flexipages({ instance_id, limit? })` lists Lightning pages (FlexiPages — App Builder record/app/home pages): `{ id, developer_name, master_label, entity_definition_id, type }`. `salesforce_get_flexipage({ instance_id, flexipage_id })` returns one page's editable `Metadata` + `FullName`. Read-only, not toggle-gated. ### `salesforce_save_flexipage` Input: `{ instance_id, developer_name, metadata, validate_only? }`. **OWNER-ONLY write (`writes.layouts` toggle).** Deploys a Lightning page — updates an existing page in place (live immediately, no draft state) or creates a new one (upsert by developer name). A brand-NEW page is deployed but NOT visible until it's activated/assigned in the Lightning App Builder (org default / app / record type assignments live in other metadata and are deliberately out of scope). FlexiPage metadata is the most complex layout format — component errors surface from the deploy verbatim. ### `salesforce_patch_flexipage` Input: `{ instance_id, developer_name, patches?: [{ component_identifier, property, op?, value?, value_list? }], field_ops?: [{ op: add|remove|move|set_behavior, field, after?, before?, section?, column?, ui_behavior?, identifier? }], structure_ops?: [{ op: add_section|add_tab|move|rename|set_visibility|remove, target?, label?, columns?, tab?, after?, before?, visibility? }], validate_only?, test_level?, run_tests? }` (at least one patch, field op or structure op; max 100 in total). **OWNER-ONLY write (`writes.layouts` toggle).** Changes INDIVIDUAL component properties on a Lightning page without resending the page. **Prefer this over `salesforce_save_flexipage` for every edit to an existing page**: that tool replaces the whole definition, real record pages run to hundreds of thousands of characters, and a transcription slip silently deletes components — which `validate_only` does NOT catch, because a page missing a component is still structurally valid. This keeps the round-trip server-side: fetch → patch in memory → verify component/field/region counts, the identifier set and every unaddressed component's property fingerprint are unchanged → deploy. If anything else drifted it refuses and deploys nothing. Get `component_identifier` (e.g. `lst_dynamicRelatedList21`) and the property name from `salesforce_get_flexipage`. A property carries EITHER a scalar (`value`) OR a list (`value_list` → `valueList.valueListItems`) — pass exactly one. `op: "remove"` deletes the property. An unknown identifier, or removing a property that is not set, is an ERROR, never a silent no-op. **`field_ops`** edit Dynamic Forms fields: add / remove / move a field (`field` = `Foo__c` or `Record.Foo__c`) placed `after`/`before` another field or at the end of `section` (field-section label or identifier) + 1-based `column`, or change its `ui_behavior` (`none` | `readonly` | `required`). The verification then also requires the page's field set to equal before − removed + added. A field that sits on the page twice needs `identifier` (the error lists the instances). **`structure_ops`** edit sections, tabs and show/hide rules: `add_section` { `label`, `columns` 1|2, `after`/`before` a sibling or `tab` }, `add_tab` { `label`, `after`/`before` another tab }, `move` { `target`, `after`/`before`/`tab` } (reorder sections, move a section to another tab, reorder tabs), `rename` { `target`, `label` }, `set_visibility` { `target` (section, tab, component or field), `visibility`: { `criteria`: [{ `left_value` ("Record.Status", "$User.Profile.Name"), `operator` EQUAL|NE|GT|GE|LT|LE|CONTAINS, `right_value` }], `boolean_filter`? } or `null` to always show }, `remove` { `target` } (an EMPTY section or non-default tab only). Targets are a section label, tab title ("Details" matches "ℹ️Details") or identifier. Non-`remove` structure ops run before `field_ops`, `remove` after — so one call can add a section, move fields into it and delete the section that was emptied. The verification additionally proves no component changed its container or visibility rule unless an op addressed it. Pages that show `force:detailPanel` render the classic layout — use `salesforce_patch_layout` there. Returns the before/after of every changed property, `field_changes` (where each field landed), `structure_changes` plus the verified structure. Live immediately (no draft state). ### `salesforce_patch_flow` — change one thing in a flow without resending it `salesforce_save_flow` needs the **whole** definition, and a real flow is 10–15 KB of JSON. Transcribing all of it to change one filter is how a nightly flow that writes Account fields org-wide quietly starts doing something else: the deploy succeeds, `status: Draft` looks right, and a flow missing a filter is still a valid flow. **Prefer `salesforce_patch_flow` for every edit to an existing flow.** ``` salesforce_patch_flow({ instance_id: 1, full_name: "Contract_Replace", patches: [{ element: "Get_Open_Contracts", // the element's `name` (unique across the flow) property: "filters", op: "append", // set | append | remove value: { field: "Status", operator: "NotEqualTo", value: { stringValue: "Draft" } } }], validate_only: true // dry run — creates no Draft version at all }) ``` The round-trip stays on the server: it fetches the version, patches in memory, and **verifies that nothing except the addressed properties changed** — element count, **connector count** (the flow's wiring, which nothing else checks), the set of element names, and every other element's property fingerprint. Any other drift and it refuses, deploying nothing. - `element` is the element's `name`. Nested named elements work too (a decision's `rules`, a screen's `fields`), and the start element — where entry criteria live — is addressed as **`"start"`**. - Ops: `set` (replace or create), `append` (push ONE item onto a list, creating the list if absent), `remove` (delete the property). Removing one item *from* a list is not an op — read it, then `set` the list you want. - Patching `name` is refused: renaming an element means rewriting every connector that references it. - A missing element or property is an **error listing the real names**, never a silent no-op. - Like `salesforce_save_flow` it always creates a new **inactive (Draft)** version; the live flow is untouched until `salesforce_activate_flow`. - `from_version` (`latest` default, or `active`) picks which version the patch is based on — they differ whenever a newer Draft exists. The one used comes back as `source_version_number`. ### Deploys are async — `status: "pending"` and `salesforce_deploy_status` Every Metadata API deploy tool (`salesforce_deploy_metadata`, `salesforce_save_flow`, `salesforce_patch_flow`, `salesforce_save_field`, `salesforce_create_object`, `salesforce_save_layout`, `salesforce_save_flexipage`, `salesforce_patch_flexipage`) returns a **`request_id`**, and returns **`status: "pending"`** when the deploy was still running after ~45s. `pending` is **not a failure**. The package is posted and Salesforce is finishing it; the tool stops waiting so the call returns inside the MCP transport's own timeout rather than dying at ~60s with nothing to show for it. Poll: ``` salesforce_deploy_status({ instance_id: 1, request_id: "0AfaV0000019IunSAE" }) → { request_id, status: "pending" | "completed", done, validate_only, components: [{ type, full_name, id, created, changed }] } ``` A deploy that **failed** is reported by this tool as an error carrying the same component failures, Apex test failures and coverage warnings the deploy call would have raised — one failure format wherever the failure landed. **Do not guess the outcome, and do not re-run the deploy.** Inferring it from `FlowVersionView.Status` or a `LastModifiedDate` is unreliable, and a blind retry is worse: the first deploy is still in flight, so repeating it applies the change twice (two flow versions, or two deploys racing on one component). ### `salesforce_deploy_metadata` Input: `{ instance_id, components: [{ type, full_name, metadata?, files? }], validate_only?, test_level?, run_tests? }`. **OWNER-ONLY write.** Config types need the `writes.metadata` toggle; `ApexClass`/`ApexTrigger` need the SEPARATE `writes.apex` toggle, and a package mixing both needs both. Both are their own switch, default OFF. The generic Metadata API deploy: the one path for org-configuration types that have no dedicated tool, plus Apex. UPSERT — the same call creates a component that does not exist and updates one that does, so there is no create/update split. Supported `type` values: `ValidationRule`, `RecordType`, `CompactLayout`, `WebLink`, `ListView`, `FieldSet`, `BusinessProcess` (object-scoped — `full_name` must be `"