@blaze283/social-agent-mcp

Stdio MCP wrapper that surfaces tools from @blaze283/social-agent-plugin to MCP clients (Claude Code, etc.) by forwarding each call to the plugin's agent-auth dispatch route.

Status: workaround

This package exists because Paperclip does not currently surface plugin-contributed tools to agents as MCP tools. Tracked upstream:

• paperclipai/paperclip#4192 — [platform] Plugin tools should auto-register as MCP tools

Related platform bugs that shape the design (board-only auth on the platform's plugin-tool dispatcher):

• #1198 — fix: plugin tool routes block agent access
• #3271 — Agent JWTs cannot access plugin tool endpoints
• #3273 — Plugin tool execute requires projectId

When #4192 ships, this repo gets deleted. Don't build anything load-bearing on it.

Architecture

agent (e.g. Claude Code)
  │   stdio
  ▼
social-agent-mcp                                  ← this package
  │   HTTP, agent's own bearer token (PAPERCLIP_API_KEY)
  ▼
POST /api/plugins/<pluginId>/api/tools/dispatch   ← plugin's agent-auth route
  │   in-process RPC
  ▼
social-agent-plugin worker (>= 0.3.0)
  │   HTTPS, OAuth token
  ▼
api.linkedin.com

The MCP holds no LinkedIn credentials and makes no LinkedIn HTTP calls. It only speaks to Paperclip. The plugin remains the credential vault and the active LinkedIn caller.

The MCP authenticates as the agent. There is no second principal (no board API key, no user identity) — the agent calls plugin tools as itself.

Requirements

• @blaze283/social-agent-plugin v0.3.0 or newer installed in the target Paperclip instance. Earlier versions either don't expose the agent-auth dispatch route or register under a different plugin id. linkedin_comment additionally requires plugin v0.4.0 or newer; linkedin_repost requires plugin v0.6.0 or newer.

Tools

| MCP tool | Plugin tool name | Purpose | |---|---|---| | social_list_channels | social-list-channels | List supported social channels and whether each is enabled. | | social_list_connections | social-list-connections | List connected accounts on a channel. Use first to get a connectionId. | | linkedin_post | linkedin-post | Publish a post. Posts immediately. Confirm with the user first. | | linkedin_react | linkedin-react | React (LIKE by default) to a LinkedIn post URL or URN. | | linkedin_comment | linkedin-comment | Post a top-level text comment (≤ 1250 chars) on a LinkedIn post URL or URN, with optional inline @mentions. | | linkedin_repost | linkedin-repost | Reshare a LinkedIn post (URL or URN), optionally with quote commentary (≤ 3000 chars). |

Schemas mirror social-agent-plugin/src/manifest.ts.

Configuration

Read at startup from the inherited process env. Normally injected by Paperclip's adapter when launching an agent run.

| Variable | Required | Default | |---|---|---| | PAPERCLIP_API_KEY | yes | — (agent bearer token) | | PAPERCLIP_COMPANY_ID | yes | — (UUID of the company that owns the connection) | | PAPERCLIP_API_URL | no | http://localhost:3100 |

If a required var is missing, the MCP fails at startup — it logs Failed to start social-agent MCP server: Missing <VAR>... to stderr and exits with code 1. The MCP client will see the connection close, not a graceful per-tool error. This matches the model: outside a Paperclip-launched agent run, the MCP has nothing to do.

For desk-use under MCP inspector or any other non-agent context, supply the vars explicitly on the command line — see Manual verification below.

Install (local-path)

cd /path/to/your/directory/social-agent-mcp
pnpm install
pnpm build

Register at user scope:

claude mcp add --scope user paperclip-social \
  -- node /path/to/your/directory/social-agent-mcp/dist/stdio.js

No -e flags. The MCP inherits PAPERCLIP_API_KEY, PAPERCLIP_COMPANY_ID, and PAPERCLIP_API_URL from the agent's process env.

Manual end-to-end verification

Requires a running local Paperclip with @blaze283/[email protected]+ installed and at least one LinkedIn account connected.

1. pnpm install && pnpm build && pnpm test
2. Inside an agent run (the normal path). Trigger a Paperclip agent run on an issue in the company that owns the connection. Have the agent call:
   • social_list_connections { channel: "linkedin" } → expect connections with status: "active".
   • linkedin_react { connectionId, post: "<linkedin URL>", reactionType: "LIKE" } → verify the reaction appears on LinkedIn, then delete it.
3. Desk-use under MCP inspector (debugging only). Supply the env explicitly so startup doesn't fail:

   PAPERCLIP_API_URL=http://localhost:3100 \
   PAPERCLIP_API_KEY=<agent key> \
   PAPERCLIP_COMPANY_ID=<your company UUID> \
     npx @modelcontextprotocol/inspector node dist/stdio.js

   The agent key must belong to an agent in the same company as the connection — the plugin's auth: "agent" route resolves the company from the request body and requires it to match the calling agent's company.

If a tool call fails, the response identifies the source: schema (your call args), paperclip (HTTP / auth — see cta field for hint), or tool-dispatch (plugin's own error code, e.g. CONNECTION_NOT_FOUND, CHANNEL_NOT_CONFIGURED).

Development

• pnpm test — vitest, all fetch mocked. No live Paperclip or LinkedIn.
• pnpm typecheck — tsc --noEmit.
• pnpm build — emits dist/.

Out of scope

• Any change to Paperclip core.
• A board-user / non-agent dispatch path. The plugin route is auth: "agent" by design — there's no parallel auth: "board" surface. Desk-use under MCP inspector still works, but only when authenticated as an agent (see Manual verification).