🔗 Skill for PicSee URL Shortener

An MCP-based Agent Skill for PicSee — URL shortening, QR code generation, click analytics, and link management.

The skill is just documentation: it points your AI agent at the public PicSee MCP server (https://api.picsee.io/mcp) and explains how to use the tools. No Node.js install, no CLI, no local token files — authentication is handled by OAuth 2.1 + PKCE via the MCP client.

🌟 What's new in v3.0.0

• CLI → MCP: the entire v2.x CLI (node cli/dist/cli.js …) is gone. All functionality is now exposed as MCP tools served from api.picsee.io/mcp.
• OAuth 2.1 + PKCE: replaces local AES-256 token encryption. Tokens are managed by your MCP client, not by this skill. Dynamic Client Registration means there's no manual app setup.
• Anonymous mode still works: create_short_link is callable without auth — perfect for one-off shortenings.
• No Node.js requirement: works in any MCP-capable client, including ones that can't execute Node (e.g. Cursor, web-based agents).
• Agent attribution built in: the server documents the convention of setting externalId to the AI agent's name (Claude Code, Cursor, Codex, …) so account owners can see which agent created which link.

Migrating from v2.x? See the Migration section.

⚙️ Installation by Platform

The skill consists of two parts:

1. Skill content (SKILL.md + this README) — placed in the platform's skills directory so the agent auto-discovers usage instructions.
2. MCP server registration — added to the platform's MCP config so the agent can actually call the tools.

Claude Code

# 1. Install the skill
cp -r picsee-short-link ~/.claude/skills/picsee-short-link

# 2. Register the MCP server
claude mcp add --transport http picsee-short-link https://api.picsee.io/mcp

Or add manually to ~/.claude.json (or project .mcp.json):

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

Cursor

Place the skill in .cursor/skills/picsee-short-link/, then edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

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

For Cursor, use https://api.picsee.io/mcp/auth when you need to sign in (OAuth). Anonymous use (create_short_link only) can stay on https://api.picsee.io/mcp.

Antigravity

Antigravity speaks MCP Streamable HTTP natively. Edit ~/.gemini/config/mcp_config.json (it shares Gemini's config dir, and uses the key serverUrl):

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

Then open Settings → Customizations → Installed MCP Servers, click Refresh, and the server appears. Click Authenticate next to it to sign in via OAuth and unlock the full authenticated tool set (anonymous mode exposes only create_short_link).

Place SKILL.md in Antigravity's skills directory so the agent picks up usage guidance.

Hermes Agent

Hermes Agent (Nous Research) speaks MCP natively as both client and server. Edit ~/.hermes/config.yaml and add the server under mcp_servers, using auth: oauth so Hermes runs the browser sign-in flow on the first authenticated call:

mcp_servers:
  picsee-short-link:
    url: "https://api.picsee.io/mcp"
    auth: oauth

On first authenticated call, Hermes prints an authorize URL (and opens your browser when possible), then waits for the OAuth callback on a local loopback port. Tokens are cached at ~/.hermes/mcp-tokens/picsee-short-link.json (mode 0o600) and reused silently until refresh fails. For anonymous use (create_short_link only), drop the auth: oauth line.

Drop the skill folder into ~/.hermes/skills/picsee-short-link/ (containing SKILL.md) — Hermes loads it immediately, no registration needed.

Codex / Codex CLI

Add the server with the Codex CLI:

codex mcp add picsee-short-link --url https://api.picsee.io/mcp

Or add it directly to ~/.codex/config.toml:

[mcp_servers.picsee-short-link]
url = "https://api.picsee.io/mcp"

Then authenticate it with OAuth:

codex mcp login picsee-short-link --scopes user:read,user:write

Codex supports remote MCP servers over Streamable HTTP via --url, and MCP server configuration is shared between the CLI and the IDE extension. platform.openai.com

If you use skills, place SKILL.md at:

~/.codex/skills/picsee-short-link/SKILL.md

OpenClaw / ClawHub

clawhub install picsee-short-link

Or browse: https://clawhub.ai/PicSeeInc/picsee-short-link

ClawHub auto-registers the MCP server from the skill's metadata.

claude.ai (Web)

Upload the skill folder under Customize → Skills. Add the MCP server in Settings → Connectors → Add custom connector with URL https://api.picsee.io/mcp.

Generic MCP client

Any client that speaks MCP Streamable HTTP can register the server directly:

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

For clients that only support stdio, use the mcp-remote bridge from npm:

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

🤖 Compatibility Matrix

Any MCP-compliant client should work — the matrix above is just the integrations we've tested.

🧩 Tools

create_short_link is the only tool callable anonymously. The other 14 require OAuth.

No QR or chart tool on the server — those are agent recipes against public services (api.qrserver.com, quickchart.io). See SKILL.md → Agent Recipes.

Full parameter tables for every tool live in SKILL.md. The MCP server is also self-describing via tools/list — that is the source of truth.

🔑 Authentication

1. Register the MCP server in your client (see Installation).
2. Ask the agent to do something that requires auth (e.g. "show me analytics for my last link").
3. The MCP client opens a browser to https://public-api-oauth.picsee.io/oauth/authorize.
4. Sign in to PicSee and approve the user:read / user:write scopes.
5. Done — the client stores the token. Future calls are silent until the refresh token expires.

The skill folder never touches your token. All credential handling lives in your MCP client.

🔒 Security

OAuth metadata is published at https://api.picsee.io/.well-known/oauth-protected-resource, with the authorization server at https://public-api-oauth.picsee.io/.well-known/oauth-authorization-server.

🧭 Agent attribution

The MCP server asks calling agents to set externalId to their own product name on create_short_link, so PicSee account owners can attribute API usage. The skill tells your agent to default to:

Claude Code · Cursor · Codex · Antigravity · OpenClaw · Gemini CLI · Copilot · ChatGPT

Users can always override by explicitly passing their own externalId.

📁 Project Structure

picsee-short-link/
├── SKILL.md     # Agent Skills definition — read by your agent
├── README.md    # This file — read by humans
└── _meta.json   # ClawHub registry metadata

No cli/ and no references/ in v3 — the MCP server is self-describing via tools/list, and the REST API is now an implementation detail of the server.

Migration from v2.x

# 1. Remove the old encrypted token + salt files
rm -f ~/.openclaw/.picsee_token ~/.openclaw/.picsee_salt

# 2. Remove the old CLI build artifacts wherever the skill was installed
rm -rf ~/.claude/skills/picsee-short-link/cli
rm -rf ~/.openclaw/workspace/skills/picsee-short-link/cli
rm -rf .cursor/skills/picsee-short-link/cli

# 3. Reinstall the v3 skill (see Installation above) and register the MCP server.
# 4. Ask the agent to do something authenticated — sign in via browser when prompted.

No API token migration is needed — OAuth issues fresh credentials from scratch.

📖 Resources

• PicSee Website: https://picsee.io
• Developer Docs: https://picsee.io/developers
• MCP Spec: https://modelcontextprotocol.io
• Agent Skills Spec: https://agentskills.io

📄 License

MIT