How to do it
- Create an agent key In https://app.socialhandoff.com, open Connections, add an agent named Claude Desktop, and pick the networks and permissions it gets. Start with draft only. Copy the key; it is shown once.
- Open the config file In Claude Desktop, open Settings, then Developer, then Edit Config. This opens claude_desktop_config.json (on macOS in ~/Library/Application Support/Claude/, on Windows in %APPDATA%\Claude).
- Add the server Paste the mcpServers block below, replace YOUR_AGENT_KEY, and save. Node.js must be installed because the server runs through npx.
- Restart Claude Desktop Quit the app fully and open it again. The tools menu in the chat box should list the SocialHandoff tools such as plan_week and draft_post.
- Send a first prompt Ask Claude to draft one post. It lands in your approval inbox as pending, where you approve, edit, or reject it.
{
"mcpServers": {
"social": {
"command": "npx",
"args": ["-y", "socialhandoff-mcp", "--url", "https://app.socialhandoff.com", "--key", "YOUR_AGENT_KEY"]
}
}
}What Claude Desktop can do once connected
Claude Desktop runs the SocialHandoff MCP server as a local process through npx. The process talks to your workspace with the agent key you pasted, so Claude only sees the networks and permissions that key allows. It never holds your X or LinkedIn tokens; those stay encrypted on the server.
With the default draft permission, Claude can:
- Call
plan_weekto lay out a week of posts. The calendar card renders inside the chat, and nothing is scheduled. - Call
draft_postto create a pending post for one or more networks. - Call
preview_poststo render the approval card, so you see per-network length checks before you open the inbox. - Read your voice rules with
get_brand_memoryand follow them while writing. - Call
list_poststo see what is already queued, so it does not repeat last week.
If you also grant schedule and analytics, Claude can propose a slot with schedule_post and read results with get_insights. It still cannot approve a draft it wrote. Approval happens in the inbox, on the phone swipe stack, or with an owner key.
Prompts that work well
- "Read my brand memory, then plan next week: 3 LinkedIn posts and 5 short X posts about our v2.4 release."
- "Turn this blog post into a 4-part Bluesky thread. Keep each part under 300 characters and add alt text to the diagram."
- "List what is pending for Mastodon and tell me which drafts break my voice rules."
Paste long source material straight into the chat. Claude Desktop is good at condensing a doc or transcript into several network-specific drafts in one pass.
Permissions to grant
Give the Claude Desktop key draft only on day one. After a run of clean approvals you can move it up the trust ladder, network by network, or let a policy with autoPromote do it. A guardrail failure, such as a banned topic or missing alt text, drops it back to draft-only at once.
Troubleshooting
- No tools appear: the JSON is probably invalid, or the app was not fully quit. Check the MCP log in Settings, then Developer.
npxnot found: install Node.js, or give the full path tonpxincommand.- 401 from the server: the key was revoked or mistyped. Mint a new one; old keys are stored only as hashes and cannot be shown again.
- A draft is rejected with 422: a guardrail caught it. Read the message; it names the rule.
Run npx socialhandoff-mcp doctor --url https://app.socialhandoff.com --key YOUR_AGENT_KEY in a terminal to check the key and server health outside the app.
Per-network guides: Claude Desktop for X, Claude Desktop for LinkedIn, Claude Desktop for Bluesky, Claude Desktop for Mastodon, and Claude Desktop for Threads.