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:
- Dynamic Client Registration →
https://public-api-oauth.picsee.io/oauth/register - Browser →
https://public-api-oauth.picsee.io/oauth/authorize - User signs in to PicSee and grants
user:read+user:write - Client receives access + refresh tokens via PKCE/S256
- 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.
| Field | Required | Notes |
|---|---|---|
url | ✅ | Destination URL, ≤2048 chars |
encodeId | Custom slug, 3–90 chars (letters / digits / _ / - / Chinese). Must be globally unique — conflicts return PUB00503 | |
domain | pse.is or a BSD from get_my_domains. Ignored when called anonymously | |
externalId | 1–100 chars. Agents SHOULD default this to their own product name — see Attribution | |
utm | { source, medium, campaign, term, content } | |
title | OG preview title, 3–300 chars | |
description | OG preview description, 3–300 chars | |
imageUrl | OG preview image URL | |
tags | Array of up to 3 tag names — use get_my_tags to offer a picker | |
targets | Device-specific redirects, see below | |
fbPixel | Meta Pixel ID — must already be saved in PicSee (get_my_tracking_tools) | |
gTag | GTM container ID — must already be saved in PicSee (get_my_tracking_tools) | |
pathFormat | { key: "<param-name>" } — Path Parameterization add-on (paid Advanced) |
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
| Field | Required | Notes |
|---|---|---|
startTime | Taipei time YYYY-MM-DDTHH:mm:ss. Defaults to 30 days before endTime | |
endTime | Taipei time YYYY-MM-DDTHH:mm:ss. Defaults to current hour. Max 31-day range |
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, name } pairs. name values are what tags accepts 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
| Field | Notes |
|---|---|
limit | 1–50, default 20 |
startTime | Taipei time YYYY-MM-DDTHH:mm:ss. Returns links created at or before this timestamp — i.e. queries backward. Default = now |
prevMapId | Cursor: return links with mapId older than this. Combine with startTime for AND filtering |
isAPI | true (default) = only API-created links; false = only website-created |
isStar | true = starred only. Default false |
externalId | Exact-match filter |
search.encodeId | Exact slug — priority 1, overrides all other search fields |
search.authorId | Filter by author's PicSee user ID — priority 2 |
search.tag | Tag name, 3–30 chars — priority 3 |
search.keyword | Substring, 3–30 chars — priority 4 |
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
| Field | Required | Notes |
|---|---|---|
encodeId | ✅ | Slug of the link to edit |
url | New destination. May be rejected with PUB00510 if the new origin is on a different brand | |
domain | ||
title / description / imageUrl | 3–300 chars for text fields | |
tags | Up to 3 | |
targets | Same enum as create_short_link | |
fbPixel / gTag | Pass null to clear | |
utm | Pass null to clear all UTM params | |
expireTime | Future Taipei time YYYY-MM-DDTHH:mm:ss, or null to remove. Requires the expiration add-on |
delete_short_link
| Field | Required | Notes |
|---|---|---|
encodeId | ✅ | |
value | delete (default) = move to trash; recover = restore from trash |
- 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.
| Tool | Returns |
|---|---|
get_link_overview | Total clicks, unique clicks, destination URL, domain, HTTPS flag, creation time. Use for at-a-glance summaries |
get_link_daily_clicks | Time-series of total + unique clicks aggregated by day. Use as raw data for chart rendering |
get_link_platforms | Unique-click breakdown by device (iphone, android, windows, macintosh, …). Aggregate to mobile/desktop client-side if needed |
get_link_referrers | Unique-click breakdown by referrer (search engines, social, AI agents, long-tail). Clicks without referrer info → direct |
get_link_regions | Unique-click breakdown by country (no city-level data). Unknown countries → Others (code: "others") |
get_link_audience_labels | Interest + brand labels. Privacy guard: only returns data when the link has >100 lifetime unique clicks; otherwise both arrays come back empty. No startTime / endTime — covers link lifetime |
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.
| Agent | Recommended externalId |
|---|---|
| Claude Code | Claude Code |
| Cursor | Cursor |
| Codex / Co |