promptbin-mcp

PromptBin MCP bridge for Claude Code / Desktop. 44 tools to share, discover, and manage AI coding sessions and curated articles — straight from your terminal.

• Search sessions by keyword/tag and fork others' work
• Share a new session with markdown + file attachments (base64)
• Curate articles with OG metadata, collect 필독 (must-read) learning notes
• Like, bookmark, comment, follow — all over OAuth or API key auth

Quick Start

The fastest way — one command, browser login, done:

claude mcp add promptbin -- npx -y promptbin-mcp

Restart Claude Code, then try:

"List the top 5 trending sessions on PromptBin" "Share this Claude chat as a new session with tag debugging" "Show me the most bookmarked articles tagged rag"

Setup Options

Option 1: npm + OAuth (recommended)

No API key, no config. The browser opens once for login, tokens are cached locally.

claude mcp add promptbin -- npx -y promptbin-mcp

Option 2: npm + API Key

Skip browser entirely. Generate at Settings → API Keys:

claude mcp add promptbin -- env PROMPTBIN_API_KEY=pb_your_key npx -y promptbin-mcp

API keys are prefixed pb_ and stored as SHA-256 hashes server-side.

Option 3: HTTP Direct (no npm)

claude mcp add --transport http promptbin https://promptbin-woad.vercel.app/api/mcp

This uses the built-in MCP OAuth flow — no wrapper needed.

Available Tools

🔹 Sessions (20)

AI 코딩 대화를 공유·큐레이션·포크·토론하는 모든 경로.

| Tool | Auth | Description | |------|:---:|-------------| | share_session | ✓ | Publish a new session (markdown + up to 5 base64 attachments) | | list_sessions | ✓ | Search by keyword, tag, or sort by latest/trending | | get_session | ✓ | Full markdown content + attachments by slug | | update_session | ✓ | Edit your session (owner or admin) | | delete_session | ✓ | Remove your session + attachments | | fork_session | ✓ | Copy a public session to your account with reference | | get_my_library | ✓ | Your bookmarked / created / liked sessions (merged, deduped) | | list_my_drafts | ✓ | Your unpublished draft sessions and/or articles | | list_following_sessions | ✓ | Public session feed from users you follow | | toggle_like | ✓ | Like / unlike | | toggle_bookmark | ✓ | Bookmark / unbookmark | | list_comments | ✓ | Read comments (threaded, cursor pagination) | | add_comment | ✓ | Post a comment or reply | | update_comment | ✓ | Edit your own comment | | delete_comment | ✓ | Remove your own (or any, if admin) | | toggle_comment_like | ✓ | Like / unlike a session comment | | create_suggestion | ✓ | Submit a prompt-improvement suggestion on a session | | resolve_suggestion | ✓ | Accept or reject a suggestion (session author only) | | get_popular_tags | ✓ | Trending session tags | | follow_user | ✓ | Follow / unfollow a user |

🔸 Articles (15)

레퍼런스 링크 큐레이션 + 필독 학습 노트.

| Tool | Auth | Description | |------|:---:|-------------| | share_article | ✓ | Share a URL with auto OG parsing + tags + optional attachments | | list_articles | ✓ | Latest or trending, filter by tag/keyword | | get_article | ✓ | Full details, optionally include reviews/comments/attachments | | update_article | ✓ | Edit (URL change re-parses OG only when changed) | | delete_article | ✓ | Remove + cleanup attachments | | get_my_articles | ✓ | Your bookmarked / created / liked articles (merged, deduped) | | toggle_article_like | ✓ | Like / unlike | | toggle_article_bookmark | ✓ | Bookmark / unbookmark | | get_popular_article_tags | ✓ | Trending article tags | | submit_article_review | ✓ | Write a learning note (필독 articles only, min 50 chars) | | update_article_review | ✓ | Edit your learning note | | delete_article_review | ✓ | Remove (owner or admin) | | list_article_reviews | ✓ | Read all notes (offset pagination) | | add_article_comment | ✓ | Discussion comment | | list_article_comments | ✓ | Top-level comments (cursor pagination) |

🔔 Account & Notifications (9)

알림 관리 + 계정/환경설정.

| Tool | Auth | Description | |------|:---:|-------------| | get_notifications | ✓ | List your notifications (read + unread activity) | | get_unread_count | ✓ | Count your unread notifications | | mark_notification_read | ✓ | Mark one notification as read | | mark_all_notifications_read | ✓ | Mark all your notifications as read | | delete_notification | ✓ | Delete one notification | | delete_all_notifications | ✓ | Delete all your notifications | | update_profile | ✓ | Update your profile (username / avatar) | | get_notification_settings | ✓ | Read your notification category preferences | | update_notification_settings | ✓ | Update your notification category preferences |

Resource

promptbin://sessions/{slug} — plain markdown fetch of any public session by slug. Useful for agents that want to read content without parsing JSON responses.

How It Works

This package wraps mcp-remote with a small anchor DCR layer. On every spawn cli.mjs:

1. Calls POST /oauth/register on the PromptBin server (idempotent DCR — same metadata → same client_id, see PR #63) with normalized loopback redirect_uris (port-less http://localhost/oauth/callback + http://127.0.0.1/oauth/callback)
2. Injects the returned client_id into mcp-remote via --static-oauth-client-info
3. Spawns mcp-remote pointed at https://promptbin-woad.vercel.app/api/mcp

If PROMPTBIN_API_KEY is set, OAuth is skipped entirely and Authorization: Bearer pb_... is injected instead. The actual MCP protocol handling, PKCE flow, and stdio↔HTTP bridging all happen inside mcp-remote.

┌─────────────┐  stdio   ┌──────────────────┐  HTTP   ┌──────────────────────┐
│ Claude Code │ ◄──────► │ promptbin-mcp    │ ◄─────► │ PromptBin /api/mcp   │
└─────────────┘          │  ├ anchor DCR    │         │  44 tools            │
                         │  └ (mcp-remote)  │         └──────────────────────┘
                         └──────────────────┘                  │
                                  │                            │
                          OAuth 2.1 + static-client-info   AES-256-GCM tokens
                          (or API key bypass)              RLS + Rate limit

The anchor DCR / --static-oauth-client-info injection bypasses ~/.mcp-auth/ cache: NodeOAuthClientProvider.clientInformation() skips disk lookup when static info is provided, so legacy client_id formats stuck in cache cannot cause the "잘못된 redirect_uri" reauth loop (PR #82).

Under the hood on the server side:

• OAuth: PromptBin issues its own AES-256-GCM encrypted tokens (not Supabase JWT pass-through). Auth code is one-time (Upstash Redis SETNX), access token lives 1h, refresh token 30d with rotation
• verifySignedClientId is loopback port-agnostic: mcp-remote uses a dynamic callback port; the server matches redirect_uri host+path only and ignores port on loopback addresses (RFC 8252 §7.3, PR #78/#80/#82 3-layer alignment across consent / canonical-hash / signed-client)
• API keys: pb_ prefix + SHA-256 hash stored server-side, raw key only shown once at generation
• Rate limiting: Upstash Redis, separate buckets for read / authenticated / social actions

Authentication Priority

When you call a tool, server checks credentials in this order:

1. OAuth access token — verified by decryption (no network round-trip)
2. API key (pb_ prefix) — SHA-256 hash lookup
3. Reject — {"error": "invalid_token"} 401

Requirements

• Node.js 18+
• Claude Code (or any MCP-compatible client: Claude Desktop, Cline, Cursor with MCP support, etc.)

Troubleshooting

401 Unauthorized — API key invalid/expired (regenerate at Settings) or OAuth refresh token expired (remove & re-add the server). v0.2.3+ injects a fresh anchor client_id per spawn via --static-oauth-client-info, so stale ~/.mcp-auth/ cache no longer causes auth loops — manual ~/.mcp-auth/ deletion is only needed if you suspect token corruption.

Connection refused / network error — Check node -v is 18+. The package requires ES module support. If behind a corporate proxy, set HTTPS_PROXY before running.

OAuth browser doesn't open — SSH/container environments can't launch browsers. Use Option 2 (API key) instead. You can copy the authorization URL from the terminal output and open it manually in another browser.

"Rate limit exceeded" — Different buckets apply: reads are generous (60/min), writes are tighter (30/min), social actions stricter (20/min). Wait a minute and retry.

Tools show up but calls fail with empty results — If you're authenticated but seeing empty lists, your account may be restricted (PromptBin is allowlist-based). Contact the administrator.

Changes to available tools aren't reflected — Claude Code caches the MCP tool list at session start. Restart Claude Code after the server adds/removes tools.

Security Notes

• Never commit PROMPTBIN_API_KEY — treat it like a password. Keys are hashed server-side so they can't be recovered; only regenerated.
• Attachments: max 5 per request, images 2MB, other files 5MB. MIME whitelist enforced server-side (no text/* wildcard — XSS-safe).
• URL inputs (for share_article / update_article) are validated against an SSRF blocklist (RFC 1918 private ranges, loopback, link-local) before any OG fetch.
• Avatar URLs (for update_profile) are validated against a host allowlist (*.supabase.co, avatars.githubusercontent.com) using exact new URL().hostname extraction — query-string and suffix-spoofing bypasses are rejected.

Links

• 🌐 PromptBin Web
• 📚 Main Repository
• 🔧 mcp-remote (upstream)

License

MIT