Picsee Short Link

PicSee Short Link

URL shortener with rich click analytics and full link management — exposed to AI agents through the PicSee MCP server at https://api.picsee.io/mcp.

The skill ships no code: it just teaches your agent how to call the MCP server. Authentication is handled by OAuth 2.1 with PKCE (Dynamic Client Registration), so no API tokens are ever stored on disk by the skill.

---

Installation

Add the PicSee MCP server to your AI client's MCP config. Pick the transport your client supports — most modern clients speak Streamable HTTP directly.

Streamable HTTP (recommended)

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

Stdio bridge (for clients without remote-MCP support)

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

See README.md for the exact config file path on each platform.

---

Authentication

Anonymous mode (no setup)

create_short_link is callable with no credentials. Anonymous calls are pinned to pse.is and have no access to externalId filtering / attribution dashboards.

Authenticated mode (OAuth 2.1)

On the first authenticated tool call, the MCP client triggers an OAuth flow:

1. Dynamic Client Registration → https://public-api-oauth.picsee.io/oauth/register
2. Browser → https://public-api-oauth.picsee.io/oauth/authorize
3. User signs in to PicSee and grants user:read + user:write
4. Client receives access + refresh tokens via PKCE/S256
5. Token is stored by the MCP client — never by this skill

All 14 authenticated tools become available after this flow.

---

Tools

15 tools total. create_short_link is callable anonymously; the rest require OAuth.

create_short_link (anonymous OK)

Create a new short link.

targets[].target enum: ios_android, ios, ios_store, android, android_store, ios_line, ios_safari, android_fb, pc_mac, pc, mac, facebook, twitter. ios_android = all mobile; pc_mac = all desktop. App-store buckets only fire for users with the app installed.

Returns picseeUrl (the shortened link).

Account / discovery tools

get_api_status

No params. Returns the account's API plan, lifetime quota, current period usage, and plan expiration. Call this before bulk operations to confirm remaining quota.

get_api_usage_by_external_id

Returns API-link counts grouped by externalId — useful for attributing usage to agents / campaigns.

get_my_domains

No params. Lists every short-link domain on the account: brand short domains (BSDs), PicSee subdomains, shared root. Each entry flags HTTPS support and default status. Call before create_short_link if the user wants a non-default domain.

get_my_tags

No params. Returns { id, value } pairs, where value is the tag name accepted by tags on create_short_link / edit_short_link.

get_my_tracking_tools

No params. Returns previously-used UTM sources / mediums, saved Meta Pixels, and saved GTM containers. Use to populate pickers instead of asking the user to retype IDs.

list_short_links

Tip: when the user says "links from March 2026", pass startTime: "2026-03-31T23:59:59" (the end of the period) — the server queries backward from there.

edit_short_link

delete_short_link

• Starred links can't be deleted (PUB00706) — unstar via web first.
• Links trashed for >30 days can't be recovered (PUB00704).

Per-link analytics

All five tools share the same shape: required encodeId, optional startTime / endTime (Taipei YYYY-MM-DDTHH:mm:ss). Default window is the last 30 days; Advanced plan can look back up to 365 days.

---

Attribution

The create_short_link schema asks the calling agent to set externalId to its own product name when the user hasn't specified one. PicSee account owners use this to attribute API usage in their dashboard.

Rules:

• Canonical product name only — no version numbers, session IDs, or user names.
• If the user explicitly provides an externalId, always honor their value instead.

---

Agent Recipes

The MCP server intentionally doesn't ship QR or chart-rendering tools — those are easier to compose client-side from public services.

Generate a QR code from a short link

Construct a URL against api.qrserver.com:

https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=

Surface the URL inline if your client renders images; otherwise return it as a link. For a larger code, change size=500x500.

Render a daily-clicks chart

1. Call get_link_daily_clicks to get the time series.
2. Build a QuickChart URL from the data:

https://quickchart.io/chart?c={type:'line',data:{labels:['2026-03-01',...],datasets:[{label:'Clicks',data:[12,38,...]}]}}

URL-encode the c parameter. Display inline if possible; otherwise return the link.

---

Common Workflows

Shorten a URL with full attribution

1. Call create_short_link with url and externalId = your agent name.
2. Return picseeUrl to the user.
3. If the user wanted a custom slug and got PUB00503, suggest an alternative.

Pick a branded short domain

1. get_my_domains to enumerate BSDs + PicSee subdomains.
2. Offer the user a picker (note which is isDefault).
3. Pass the chosen domain to create_short_link.

Show analytics for a link

1. get_link_overview for the headline numbers.
2. If the user wants breakdowns, call one or more of get_link_daily_clicks / get_link_platforms / get_link_referrers / get_link_regions / get_link_audience_labels.
3. For audience labels: warn the user if the link has ≤100 unique clicks (data will be empty due to the privacy guard).

List the user's recent links

1. Call list_short_links with the user's filters.
2. If they say "March 2026", pass startTime: "2026-03-31T23:59:59".
3. Paginate with prevMapId from the last result if they ask for more.

Migrate a link to a new destination

1. edit_short_link with encodeId + new url.
2. If you get PUB00510, the brand of the new URL doesn't match. Tell the user.

Track API usage by agent

get_api_usage_by_external_id with no params returns the last 30 days, grouped by attribution tag. Useful for "which AI created most of my links?"

---

Migration from v2.x

v2.x was a Node.js CLI that stored an encrypted API token under ~/.openclaw/. v3.0.0 removes that entirely — no CLI, no token files, no Node.js requirement on the agent side.

# Clean up v2 artifacts
rm -f ~/.openclaw/.picsee_token ~/.openclaw/.picsee_salt
rm -rf ~/.claude/skills/picsee-short-link/cli
rm -rf ~/.openclaw/workspace/skills/picsee-short-link/cli

Behavioral changes:

• Auth: long-lived API token → OAuth 2.1 + PKCE (browser sign-in on first authenticated call)
• QR / chart: were CLI subcommands → now agent recipes against api.qrserver.com / quickchart.io
• delete vs recover: were two CLI commands → one tool delete_short_link with value: "delete" | "recover"
• Analytics: was a single analytics command → split into 6 granular tools (get_link_overview + 5 dimensional breakdowns)
• Per-account discovery: new tools get_my_domains, get_my_tags, get_my_tracking_tools, get_api_status, get_api_usage_by_external_id have no v2 equivalent

---

Error codes

---

References

• PicSee website: https://picsee.io
• Developer docs: https://picsee.io/developers
• MCP spec: https://modelcontextprotocol.io
• OAuth 2.1 (MCP profile): https://modelcontextprotocol.io/specification/draft/basic/authorization