PicSee Short Link

intent

Use this skill when a user needs to shorten a URL, create a branded short link, view click analytics (daily, platform, referrer, region, audience), or manage existing links. Anonymous mode works for basic URL shortening without login. OAuth 2.1 unlocks link management, rich analytics, custom domains, UTM tracking, QR code generation, and pixel/GTM integration. The skill exposes the PicSee MCP server at https://api.picsee.io/mcp to your agent with no local code or token storage.

inputs

MCP server connection

• Transport: Streamable HTTP (recommended) at https://api.picsee.io/mcp, or stdio bridge via npx mcp-remote https://api.picsee.io/mcp
• Network: Outbound HTTPS to api.picsee.io and public-api-oauth.picsee.io
• Config location: Add to your AI client's MCP config (see installation section below)

Authentication (two modes)

• Anonymous: No setup. create_short_link works immediately. Results pinned to pse.is domain; no externalId attribution or analytics dashboards.
• OAuth 2.1: Browser sign-in on first authenticated tool call. No API tokens stored on disk by the skill (MCP client handles token storage). Unlocks all 14 authenticated tools and full link management.

User inputs (varies by tool)

• create_short_link: destination URL (required), optional custom slug, domain, externalId, utm params, OG preview fields, device targets, tracking pixels/containers, tags
• edit_short_link: encodeId (required), any field from create_short_link plus expireTime
• delete_short_link: encodeId (required), optional recovery flag
• list_short_links: filters by date range (startTime/endTime), externalId, slug, tag, keyword; pagination via prevMapId
• Analytics tools (get_link_*): encodeId (required), optional date range; all default to last 30 days
• Discovery tools: no params required

External integrations (optional)

• Meta Pixel: Pre-configured in PicSee account via get_my_tracking_tools; pass pixel ID to fbPixel parameter
• Google Tag Manager: Pre-configured container ID via get_my_tracking_tools; pass to gTag parameter
• Custom short domains: Pre-configured BSDs retrieved via get_my_domains
• Tags / UTM presets: Retrieved from get_my_tracking_tools and get_my_tags for picker population

procedure

Installation (pick one transport)

Streamable HTTP (recommended)

1. Locate your AI client's MCP config file (typically ~/.config/cline/cline_mcp_settings.json for Cline, or equivalent for Claude Desktop, Cursor, etc.)
2. Add this entry under mcpServers:

   {
     "picsee-short-link": { "url": "https://api.picsee.io/mcp" }
   }
   

3. Save and restart your client
4. Output: MCP server registered; create_short_link is immediately callable

Stdio bridge (for clients without remote-MCP support)

1. Ensure npx is available on your system
2. Locate your AI client's MCP config file
3. Add this entry under mcpServers:

   {
     "picsee-short-link": {
       "command": "npx",
       "args": ["-y", "mcp-remote", "https://api.picsee.io/mcp"]
     }
   }
   

4. Save and restart your client
5. Output: MCP server bridged via stdio; create_short_link is immediately callable

Core workflow: shorten a URL

1. Input: user provides destination URL and (optionally) custom slug, domain, tags, utm params
2. Determine auth mode: if no authenticated tools have been called yet, check if user requested features requiring OAuth (custom domain, analytics, pixel tracking). If yes, proceed to step 3; else proceed to step 4.
3. Trigger OAuth flow (first authenticated call only):
   • MCP client opens browser to https://public-api-oauth.picsee.io/oauth/authorize
   • User signs in and grants user:read + user:write scopes
   • Client receives access + refresh tokens via PKCE/S256
   • MCP client stores tokens (not this skill)
   • Output: OAuth complete; all 14 authenticated tools now available
4. Call create_short_link with:
   • url: destination (required, ≤2048 chars)
   • encodeId: custom slug if provided (3-90 chars, globally unique, alphanumeric/dash/underscore/Chinese only)
   • domain: if user chose a branded domain via get_my_domains, pass it here; else omit (anonymous calls ignore this)
   • externalId: set to agent name (e.g. "Claude Code") if user did not specify; always honor explicit user value
   • tags: pass array of tag names if user specified; call get_my_tags first to offer a picker
   • utm: object with source/medium/campaign/term/content if user provided tracking params
   • title, description, imageUrl: OG preview fields if user provided
   • targets: device/platform-specific redirects if user provided (ios/android/mac/desktop/social/etc)
   • fbPixel, gTag: if user specified tracking, verify via get_my_tracking_tools first; pass ID or omit
5. Handle response:
   • Success: return picseeUrl (the shortened link) to user
   • Custom slug conflict (PUB00503): offer alternative slug and retry
   • Other errors: surface to user with error code
6. Output: shortened link and domain

Workflow: show analytics for a link

1. Input: user provides short link slug or encodeId
2. Call get_link_overview with encodeId:
   • Output: total clicks, unique clicks, destination URL, domain, HTTPS flag, creation time
3. Ask user if breakdown needed: "Want to see clicks by day, device, referrer, region, or audience interests?"
4. If user wants breakdown, call corresponding tool with same encodeId and optional startTime/endTime:
   • get_link_daily_clicks: time series of total + unique clicks per day
   • get_link_platforms: breakdown by device (iphone, android, windows, macintosh, etc)
   • get_link_referrers: breakdown by referrer (search engines, social, direct, AI agents, etc)
   • get_link_regions: breakdown by country code (no city-level data)
   • get_link_audience_labels: interest + brand labels (empty if <100 unique lifetime clicks; privacy guard)
5. Render output: return raw numbers or, if client supports images, render daily-clicks chart via quickchart.io (see recipes below)
6. Output: analytics data and optional chart URL

Workflow: list and manage links

1. Input: user says "show my links from March" or "list recent links" or "find link with slug xyz"
2. Call list_short_links with:
   • startTime: if user specified a month/date, use last moment of that period (e.g. "2026-03-31T23:59:59") because server queries backward
   • externalId: if user asking for links from a specific agent/campaign, pass the exact externalId
   • search.encodeId: if user gave a slug, pass it here (highest priority, overrides other filters)
   • search.tag: if user mentioned a tag, pass tag name
   • search.keyword: if user gave a substring to find in title/description, pass it
   • limit: default 20; increase if user asks for more
3. Handle pagination: if user asks for more, extract prevMapId from last result and call list_short_links again with same filters
4. For edit: call edit_short_link with encodeId and fields to change (url, domain, title, description, tags, targets, utm, expireTime, fbPixel, gTag)
5. For delete: call delete_short_link with encodeId and value: "delete" (move to trash) or value: "recover" (restore from trash)
6. Output: list of links with metadata, or confirmation of edit/delete

Workflow: discover account resources

1. Before bulk operations: call get_api_status with no params
   • Output: API plan, lifetime quota, current period usage, expiration date
   • Use to decide if remaining quota allows operation
2. To pick a custom domain: call get_my_domains with no params
   • Output: list of brand short domains (BSDs), PicSee subdomains, shared root; flags HTTPS support and default status
   • Offer user a picker and pass chosen domain to create_short_link
3. To populate tag picker: call get_my_tags with no params
   • Output: array of { id, value } pairs where value is the tag name
   • Use value (not id) when calling create_short_link or edit_short_link
4. To populate UTM/pixel pickers: call get_my_tracking_tools with no params
   • Output: previously-used UTM sources/mediums, saved Meta Pixels, saved GTM containers
   • Offer pre-filled values instead of asking user to retype IDs
5. To track API usage by agent: call get_api_usage_by_external_id with no params (or startTime/endTime)
   • Output: link counts grouped by externalId
   • Use to answer "which AI created most of my links?" or "did Claude Code stay under quota?"
6. Output: account resource inventory

decision points

Anonymous vs. authenticated call

If user only asks to shorten a URL and does not specify a custom domain, tracking, externalId, or device targets, then call create_short_link immediately in anonymous mode; OAuth is not needed.

Else if user requests any authenticated feature (custom domain, analytics, link management, pixel tracking, custom expireTime, or explicit externalId), then proceed to next call which triggers OAuth flow if not already authenticated.

Custom slug conflict

If create_short_link returns error code PUB00503, then the requested slug is already taken; suggest an alternative slug to user and retry create_short_link with new slug.

Else if error is PUB00510, then the new destination URL (on edit) is on a different brand than the original; tell user they cannot change the brand via edit, only via delete + create.

Privacy guard on audience labels

If user calls get_link_audience_labels and the link has ≤100 unique lifetime clicks, then both interest and brand label arrays will be empty; warn user that data is unavailable due to privacy threshold.

Else (>100 clicks), labels are returned normally.

Starred links cannot be deleted

If user tries to delete a starred link via delete_short_link and gets error PUB00706, then tell user to unstar the link via the PicSee web app first, then retry delete.

Trash recovery window

If user tries to recover a deleted link via delete_short_link with value: "recover" and gets error PUB00704, then the link has been in trash >30 days and is no longer recoverable; advise user to recreate the link if needed.

Date range queries use backward-time semantics

If user says "show me links from March 2026", then set startTime: "2026-03-31T23:59:59" (the last moment of the month), not the first; the server queries backward from the start time.

Else (user specifies "in the last 7 days" or "after 2026-03-15"), calculate the appropriate startTime based on backward semantics.

Advanced plan features

If user requests expireTime on create_short_link or edit_short_link, then verify via get_api_status that the account has the expiration add-on; if not, tell user this feature requires an upgrade.

Else if user requests pathFormat (path parameterization), then verify the account has the Advanced plan; if not, inform user.

Else if user queries analytics for >30 days back, then verify the account is on Advanced plan (up to 365-day lookback); if not, restrict to last 30 days.

output contract

For create_short_link

• Data format: JSON object with key picseeUrl (string, the shortened link)
• Example: { "picseeUrl": "https://pse.is/abc123" } or { "picseeUrl": "https://mybrand.io/custom-slug" }
• Guarantee: link is created, globally unique, and live immediately

For analytics tools

• Data format: JSON objects with numeric counts and time series arrays
  • get_link_overview: keys = totalClicks, uniqueClicks, destinationUrl, domain, httpsSupported, createdAt
  • get_link_daily_clicks: array of { date, totalClicks, uniqueClicks }
  • get_link_platforms, get_link_referrers, get_link_regions: array of { label, uniqueClicks } where label is device/referrer/country
  • get_link_audience_labels: arrays of { label, uniqueClicks } for interests and brands (empty if <100 lifetime clicks)
• File location: returned inline in JSON response, not written to disk
• Guarantee: data is aggregated as of query time; timezone is Taipei (Asia/Taipei)

For list_short_links

• Data format: JSON object with keys links (array) and prevMapId (string for pagination)
• Each link object: encodeId, picseeUrl, destinationUrl, domain, createdAt, totalClicks, tags, externalId, isStarred
• Guarantee: results sorted by creation time descending (newest first); pagination cursor is included if more results exist

For account discovery tools

• Data format: JSON objects specific to each tool
  • get_my_domains: array of { domain, isDefault, httpsSupported, type }
  • get_my_tags: array of { id, value }
  • get_my_tracking_tools: arrays of previousUtmSources, previousUtmMediums, savedMetaPixels, savedGtmContainers
  • get_api_status: keys = plan, lifetimeQuota, currentPeriodUsage, expirationDate, remainingQuota
  • get_api_usage_by_external_id: array of { externalId, linkCount }
• Guarantee: data reflects current account state as of query time

For edit/delete operations

• Data format: JSON object with success: true and optional message field
• On error: JSON object with error: { code, message }
• Guarantee: operation is atomic (all-or-nothing); no partial updates

outcome signal

Shortened link created

User receives a working short URL (e.g. https://pse.is/abc123) that redirects to the destination. If a custom domain was used, URL is from that domain (e.g. https://mybrand.io/custom-slug). Confirm by testing the link in a browser or curl.

Analytics displayed

User sees numeric click counts (total, unique) and optional breakdowns by day, device, referrer, region, or audience interests. If a chart was rendered, it displays a time series graph or a link to the chart image. Numbers match the PicSee web dashboard for the same link and date range.

Link list returned

User sees a paginated list of their short links with creation date, slug, destination URL, click counts, and tags. If multiple pages exist, pagination cursor is available and user can load more.

Link edited or deleted

User receives confirmation that the link was modified or moved to trash. If recovering a deleted link, confirmation shows it is now active again. Link metadata is updated across all analytics dashboards.

Account resources discovered

User receives a picker or list of their custom domains, tags, tracking tools, or API usage. This data is used to auto-populate form fields or answer "how much quota do I have left?" in subsequent operations.

OAuth sign-in complete

On first authenticated call, browser opened to PicSee login. After user signed in and granted scopes, the agent confirmed success and became able to call all 14 authenticated tools. No further login prompts appear (tokens auto-refresh).

Error surfaced clearly

If a call fails, user sees the error code (e.g. PUB00503, PUB00510) and a human-readable explanation. For conflicts (slug taken, wrong brand), the agent suggests a recovery action (new slug, recreate link,