# ity.so > ity.so is a link management and landing-page platform. Agents can create short links, design landing pages, capture leads and read analytics through a Model Context Protocol (MCP) server. ## MCP endpoint - **URL:** `https://ity.so/api/v1/mcp` (Streamable HTTP — the supported transport) - **Auth:** `Authorization: Bearer `. Create keys in the dashboard under Settings → API Keys. - **Protocol:** MCP — the server negotiates 2025-06-18, 2025-03-26 or 2024-11-05, echoing whichever version the client asks for. - A legacy HTTP+SSE transport is served at `https://ity.so/api/v1/mcp/sse`. It is best-effort and single-instance; prefer Streamable HTTP. GET on the main endpoint returns 405 by design. ## Getting started 1. Call `list_component_types` first — it returns every landing-page component, its required and optional fields, a worked example, the shared `presentation` contract (section width, surface, background role, padding, hero variants) and (for `custom_section`) the full `data-ity` hook contract. 2. Build a page with `create_bridge_page`. Pages are published by default. 3. Point traffic at it with `create_link(bridge_page_id=)` — the server resolves the page URL, so you never copy/paste it. 4. Read results with `get_analytics` and `list_form_submissions`. ## Read the destination before you describe it Before creating a link or page for a URL you have not read, call `fetch_url_metadata` on it. Write the title, description and social preview from what the page actually offers. A label invented from the slug — "AI Money Group - Build You" from /build-you — is the most common avoidable mistake here, and it is what the recipient sees in the share preview. If the page cannot be read, ask the user what it offers rather than guessing. `description` is a real field on links and is not decoration: the redirect serves it as og:description when og_description is unset, so a link with neither shares with a blank second line. ## Pick the domain deliberately `create_link` uses the organization default when no `domain` is given, and that is whichever custom domain is marked default — not necessarily the one the user has in mind, and not necessarily the one older links use. Call `list_domains` when the user names a domain or when it matters which they get. Creating on the wrong host means a live link that has to be recreated and the old one deleted. To change the default itself, `set_default_domain` — but ask first. It is org-wide and decides where every future link is published, including links made by people who are not in the conversation. It does not move existing links. The organization subdomain is a valid choice, and is what to pick when the user wants to stop defaulting to a custom domain. For a one-off, pass `domain` to `create_link` instead of changing the default. ## When something is not how you left it `get_activity` answers who changed a link or page and when, including edits made by people in the dashboard rather than through this server. Reach for it before assuming your own earlier call was wrong or that a record was lost: the usual explanation is that a teammate edited it. It reports the actor, whether the change came via the dashboard or an agent, and the old and new value of each field that changed. ## Social previews — set them, they are blank by default Anything built here exists to be shared, and a link with no preview image is markedly less likely to be clicked. Nothing warns you when these are empty, so populate them as part of creating the thing rather than as a follow-up nobody does. On `create_bridge_page` / `update_bridge_page`: `og_title`, `og_description`, `og_image_url` (plus `meta_title` / `meta_description` for search). On `create_link` / `update_link`: the same three og_ fields — the redirect serves them to crawlers before bouncing the visitor onward, so a short link previews as whatever you set here, not as its destination. Write `og_title` as the hook someone reads before deciding to click, not a restatement of the page name. If the user supplies an image, `upload_file_from_url` returns a URL usable as `og_image_url`; 1200x630 is the safe size. Responses echo `social_preview_title` and `social_preview_image` showing what a crawler will actually render after fallbacks — a null image there means the link will share as bare text. ## Lead delivery — ask about it When you create or edit a page that captures leads — `form`, `optin`, `lead_magnet`, an email-collecting `quiz`, or a `custom_section` carrying `data-ity="form"` — ask whether submissions should also be delivered to GoHighLevel, Zapier, Make, n8n or another HTTPS webhook. Note that a standard page with no form component still captures leads: one is injected at render time unless `auto_form_enabled` is false or the page is built entirely from `custom_section`. So ask even when you did not author a form yourself. If they want delivery: call `get_webhook_presets` for where the URL lives in each destination, save it with `webhook_url` and `webhook_preset`, then call `send_test_webhook`. Tell them to map fields in the destination only *after* the test arrives — GoHighLevel and Zapier build their field list from a sample they have actually received, so a mapping attempted first has nothing to bind to. **Do not block page creation on this.** If the user declines, or does not have the URL yet, carry on and say the page is finished — submissions are stored in ItyURL either way and a webhook can be added later. Responses for a page carry two booleans: `captures_leads` (whether a visitor can submit anything, accounting for the form injected at render time) and `webhook_configured` (whether a destination is set). Both are always present, so branch on them rather than inspecting components yourself. Capturing with no destination adds `suggested_next_step`; a destination on a page that captures nothing adds `warning` — that one still passes a test send, so it is easy to miss. Note `webhook_enabled` is a pause switch that defaults to true and says nothing about whether a URL exists. Pass `idempotency_key` on create calls so a retry returns the original result instead of creating a duplicate — that result is the response body stored at the time of the first call, marked `idempotent_replay: true`, so re-read the entity if you need its current state. Errors carry a stable machine-readable `code` (for example `code_taken`, `limit_reached`, `not_authorized`) plus a human message, so failures can be corrected without parsing prose. ## Tools (35) - **`analyze_cta`** — Score a CTA's effectiveness using AI. - **`attach_tracking_pixel`** — Attach one or more tracking pixels to a link or bridge page so they fire for its visitors. - **`create_bridge_page`** — Create a new bridge/landing page with full content. - **`create_bridge_page_from_template`** — Create a bridge page from a template, copying its components and branding. - **`create_link`** — Create a new short link. - **`create_routing_rule`** — Create a smart routing rule that sends different visitors to different destinations based on country, device, UTM, time of day and so on. - **`delete_bridge_page`** — Permanently delete a bridge page. - **`delete_file`** — Permanently delete a file from the media library. - **`delete_link`** — Permanently delete a link. - **`delete_routing_rule`** — Delete a smart routing rule. - **`detach_tracking_pixel`** — Stop a tracking pixel firing on a link or bridge page. - **`fetch_url_metadata`** — Read a public URL's own title, description and Open Graph tags. - **`generate_cta_variants`** — Generate AI-optimized CTA alternatives. - **`get_activity`** — Who created, changed or deleted a link or bridge page, and when. - **`get_analytics`** — Organization-wide analytics summary. - **`get_bridge_page`** — Get details and full component/branding data for a bridge page. - **`get_link`** — Get details for a specific link. - **`get_link_analytics`** — Detailed click stats for a specific link. - **`get_routing_options`** — The smart-routing vocabulary: which visitor attributes can be matched (country, device, UTM, time of day, language...), which operators exist, and which actions a rule can take. - **`get_webhook_presets`** — Where to find the webhook URL in GoHighLevel, Zapier, Make or n8n, and the order to do things in. - **`list_bridge_page_templates`** — List the ready-made bridge page templates. - **`list_bridge_pages`** — List bridge/landing pages. - **`list_component_types`** — Get full schemas, required/optional fields, and examples for all available bridge page component types. - **`list_domains`** — Short domains this organization can create links on, and which one is used by default. - **`list_files`** — List files already in the organization's media library, so you can reuse an existing asset instead of re-hosting it. - **`list_form_submissions`** — View lead capture form responses for a bridge page. - **`list_links`** — List and search short links. - **`list_routing_rules`** — List smart routing rules, in the priority order they are evaluated. - **`list_tracking_pixels`** — List the organization's tracking pixels with a health verdict and where each is attached. - **`list_webhook_deliveries`** — Delivery history for a page — did the leads actually arrive? 'abandoned' means the retry schedule ran out after about a week and that lead reached no destination; the submission is still stored and can be retried. - **`send_test_webhook`** — Send a sample payload to every webhook destination on a page and report what each returned, plus the exact JSON sent. - **`set_default_domain`** — Change which short domain this organization uses by default for new links. - **`update_bridge_page`** — Edit a bridge page — including its full component layout and branding. - **`update_link`** — Edit a link's destination, title, tags, or expiry. - **`upload_file_from_url`** — Host a file in the organization's media library by fetching it from a public URL, and return the hosted URL. ## Prompts (6) The server also exposes the MCP `prompts` capability — ready-made playbooks for the common jobs, retrieved with `prompts/list` and `prompts/get`. Clients typically surface them as slash commands. Each one carries the constraints that matter for that job, so starting from a playbook beats composing the pipeline from scratch. - **`build_lead_capture_page`** — Design a landing page with an email capture form and point a short link at it (requires `offer`). - **`design_custom_section`** — Author a freeform section in HTML and CSS, bound to the platform's data-ity hooks (requires `brief`). - **`deliver_a_file`** — Host a file, build a page that trades it for an email, and link to it (requires `asset_url`). - **`campaign_links`** — Turn a list of destinations into tagged short links, safely retryable (requires `destinations`). - **`performance_report`** — Summarize clicks, sources and captured leads, and flag what looks broken. - **`improve_page`** — Review a live page, strengthen the CTA, and update it in place (requires `page`). The same guidance is returned in the `instructions` field of the `initialize` response, so an MCP client receives it at handshake without reading this file. ## API key scopes Keys may be narrowed to a subset of permissions, and given an expiry. A key with no scopes set has full access. - `links:read` — View short links and their details - `links:write` — Create, edit and delete short links - `bridge_pages:read` — View bridge pages and their content - `bridge_pages:write` — Create, edit and delete bridge pages - `analytics:read` — View click and page analytics - `forms:read` — View lead capture form submissions - `ai:use` — Use AI features (CTA analysis and variant generation) - `media:read` — View files in the media library - `media:write` — Upload files to the media library - `pixels:read` — View tracking pixels and where they are attached - `pixels:write` — Attach and detach tracking pixels on links and pages - `routing:read` — View smart routing rules - `routing:write` — Create, edit and delete smart routing rules - `webhooks:read` — View webhook destinations and delivery history - `webhooks:write` — Send test payloads to webhook destinations ## Notes - Rate limits apply per API key; exceeding them returns `rate_limited` with a `retry_after`. - Landing-page HTML is sanitized server-side. Agent markup carries no JavaScript; interactive behaviour comes from inert `data-ity` hooks bound by a trusted runtime. - `custom_section` (freeform HTML/CSS) requires a paid plan. Prefer the `presentation` object on structured components: it keeps theming, branding and form wiring, which custom HTML loses. - A standard page with no form component gets a default lead capture form injected. Pass `auto_form_enabled: false` on create/update for a page that deliberately has none. ## Docs - API reference: `https://ity.so/api/docs` - OpenAPI schema: `https://ity.so/openapi.json`