Spaces

npx add-mcp 'https://api.spacesos.com/mcp'

Quickstart

1. Create an account with your email and the code we send.
2. In the dashboard, connect WhatsApp (scan a QR code), or Instagram, LinkedIn or Facebook Messenger (sign in).
3. Create an API key. It starts with spc_live_ and is shown once.
4. Add the MCP server to your agent, or call the REST API.

MCP server: https://api.spacesos.com/mcp · REST base URL: https://api.spacesos.com/v1 · Auth: Authorization: Bearer spc_live_xxxxxxxxxxxxxxxx

Sign up and set up from an agent

An agent can do the whole setup over the API or MCP. Only two steps need the person: reading the code from their inbox, and opening the link to connect an account. The first connect starts the Free plan. No card needed.

1. POST /signup with the email (or the create_account tool). We email a 6-digit code.
2. POST /signup/verify with the code (or verify_account). You get an API key.
3. POST /messaging/accounts/connect-link (or create_messaging_connect_link) returns a link where the person scans a QR code or signs in. The first connect starts the Free plan: 1 account and 20 actions a day.
4. To choose a plan, POST /messaging/billing/checkout (or create_messaging_billing_checkout) with plan and interval. It returns a link where the person adds a card. Do this for a second account or more than 20 actions a day.
5. GET /messaging/accounts (or list_messaging_accounts) confirms the account is live. Keys: GET, POST and DELETE /keys.

Paste this into Claude Code, Claude Desktop or any agent that can browse and run commands.

Set me up on Spaces so you can read and send my messages. Instructions: https://www.spacesos.com/llms.txt

Connect an account and choose a plan, with a key

curl -X POST https://api.spacesos.com/v1/messaging/accounts/connect-link \
  -H "Authorization: Bearer spc_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp" }'

curl -X POST https://api.spacesos.com/v1/messaging/billing/checkout \
  -H "Authorization: Bearer spc_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "success_url": "https://app.spacesos.com/dashboard", "cancel_url": "https://app.spacesos.com/dashboard" }'

Connect your agent

The MCP server gives your agent tools to list accounts and chats, read messages, reply and start chats.

Run this once in your terminal. Claude Code can then read and send your messages.

claude mcp add --transport http spaces https://api.spacesos.com/mcp --header "Authorization: Bearer spc_live_xxxxxxxxxxxxxxxx"

One MCP server per channel

https://api.spacesos.com/mcp covers every channel. Each channel also has its own server, limited to that channel's accounts and tools: https://api.spacesos.com/mcp/whatsapp, https://api.spacesos.com/mcp/instagram, https://api.spacesos.com/mcp/linkedin, https://api.spacesos.com/mcp/messenger and https://api.spacesos.com/mcp/x. The same key and the same limits apply. An account from another channel is refused.

Claude, ChatGPT, Cursor and Grok

Client	How it connects
Claude Code	claude mcp add --transport http spaces https://api.spacesos.com/mcp --header "Authorization: Bearer spc_live_xxxxxxxxxxxxxxxx"
Claude Desktop	Settings, Developer, Edit Config: add the server with mcp-remote and your key, then restart.
Claude API	Pass the URL in mcp_servers with your key as authorization_token.
ChatGPT	A custom MCP connector with the URL and the Authorization header.
Cursor	An MCP server named spaces with the URL and header, or OAuth.
Grok	The xAI API's MCP tool with the URL and header, or OAuth.
Grok Bot	OAuth, no key: it finds Spaces through /.well-known/oauth-authorization-server and you approve access.

Any of these URLs can be one of the per-channel servers above.

Which key permissions do I need?

New keys can read and send. A read-only key is enough for agents that only summarise or search your messages.

MCP tools

Two servers. https://api.spacesos.com/mcp/start needs no key and signs people up. https://api.spacesos.com/mcp takes Authorization: Bearer spc_live_xxxxxxxxxxxxxxxx and does everything else. Each tool describes its own limits, so Claude and Grok can plan around them.

Tool	Arguments	What it does
create_account	email	Onboarding server, no key. Emails the person a 6-digit code.
verify_account	signup_id, code	Onboarding server. Returns the API key and how to connect.
list_messaging_accounts	none	Connected accounts on every channel.
list_messaging_chats	account_id, cursor?, limit?, unread?	Chats on an account, newest first.
list_messaging_messages	account_id, chat_id, cursor?, limit?	Messages in a chat.
get_messaging_attachment	account_id, chat_id, message_id, attachment_id	One attachment as base64 (up to 5 MB).
reply_in_chat	account_id, chat_id, text, idempotency_key, attachments?	Reply in an existing chat. Needs a key that can send.
start_chat	account_id, to (phone, username or user_id), text, idempotency_key	Start a new chat. Subject to the new-chat limits.
create_messaging_connect_link	channel or account_id	A link the person opens to connect (QR code or login), or to reconnect.
disconnect_messaging_account	account_id	Disconnect an account; billing for it stops.
get_messaging_billing	none	Subscription status, connected accounts and monthly total.
create_messaging_billing_checkout	plan, interval	Choose a paid plan. Returns a link where the person adds a card.
get_profile	account_id, identifier	A profile on any channel. On LinkedIn it counts as a profile view.
send_invitation	account_id, identifier, message?, idempotency_key	LinkedIn: invite someone to connect.
list_invitations	account_id	LinkedIn: pending invitations you sent.
cancel_invitation	account_id, invitation_id	LinkedIn: withdraw an invitation.
search_linkedin	account_id, keywords, category?	LinkedIn: search people or companies.
list_user_posts	account_id, identifier	LinkedIn: recent posts of a person or company.
get_post	account_id, post_id	LinkedIn: one post.
list_comments	account_id, post_id	LinkedIn: comments on a post.
create_post	account_id, text, idempotency_key	LinkedIn: publish a post.
comment_on_post	account_id, post_id, text, comment_id?, idempotency_key	LinkedIn: comment, or reply to a comment.
react_to_post	account_id, post_id, reaction?, idempotency_key	LinkedIn: like, celebrate, support, love, insightful or funny.

REST API

Every request needs your key. Account ids come from GET /messaging/accounts.

Method	Path	What it does
GET	/messaging/accounts	Your connected accounts
GET	/messaging/accounts/{account_id}/chats	Chats, newest first (cursor, limit, unread)
GET	/messaging/accounts/{account_id}/chats/{chat_id}/messages	Messages in a chat
POST	/messaging/accounts/{account_id}/chats/{chat_id}/messages	Reply in a chat
POST	/messaging/accounts/{account_id}/chats	Start a chat (WhatsApp: to.phone; Instagram, X, LinkedIn: to.username; Messenger: to.user_id)
GET	/messaging/accounts/{account_id}/users/{identifier}	A profile (on LinkedIn, counts as a profile view)
GET	/messaging/accounts/{account_id}/chats/{chat_id}/messages/{message_id}/attachments/{attachment_id}	Download an attachment
POST	/messaging/webhooks	Get a signed POST for new messages, reads, reactions, comments, sends, posts and account status
POST	/messaging/webhooks/{id}/test	Send one signed example event to that webhook now
GET	/messaging/accounts/{id}/health	Is this account working, and what to do if not
PATCH	/messaging/accounts/{id}	Tag an account with your own id (external_id)
GET	/messaging/analytics/posts	How your LinkedIn and Instagram posts are doing
GET	/messaging/usage	Sends and new chats per account against its limits
POST	/messaging/accounts/{account_id}/invitations	LinkedIn: send an invitation { to, message? }
GET / DELETE	/messaging/accounts/{account_id}/invitations[/{invitation_id}]	LinkedIn: sent invitations, withdraw one
POST	/messaging/accounts/{account_id}/search	LinkedIn: search { keywords, category: people | companies }
GET	/messaging/accounts/{account_id}/users/{identifier}/posts	LinkedIn: posts of a person or company
GET	/messaging/accounts/{account_id}/posts/{post_id}[/comments]	LinkedIn: a post, its comments
POST	/messaging/accounts/{account_id}/posts	LinkedIn: publish a post { text }
POST	/messaging/accounts/{account_id}/posts/{post_id}/comments	LinkedIn: comment { text, comment_id? }
POST	/messaging/accounts/{account_id}/posts/{post_id}/reactions	LinkedIn: react { reaction }
GET	/integrations/{account_id}/tiktok/account	TikTok: account name, followers, likes and videos. Optional start_date and end_date add views and new followers
GET	/integrations/{account_id}/tiktok/videos	TikTok: your videos, newest first, with caption, link, views, likes and comments
POST	/integrations/{account_id}/tiktok/videos	TikTok: post a video from a public https link. The owner picks privacy_level and approves the exact post (owner_approved: true)
POST	/integrations/{account_id}/tiktok/photos	TikTok: post up to 35 photos as one post. The owner picks privacy_level and approves the exact post
GET	/integrations/{account_id}/tiktok/videos/{video_id}/comments	TikTok: comments on one of your videos
POST	/integrations/{account_id}/tiktok/videos/{video_id}/comments/{comment_id}/replies	TikTok: reply to a comment, once the owner approves the exact reply
GET / POST / DELETE	/keys	List, create and revoke keys
POST	/keys/{key_id}/pause, /keys/{key_id}/resume	Switch a key off and on again

List chats

curl "https://api.spacesos.com/v1/messaging/accounts/ACCOUNT_ID/chats?limit=20" \
  -H "Authorization: Bearer spc_live_xxxxxxxxxxxxxxxx"

Reply in a chat

curl https://api.spacesos.com/v1/messaging/accounts/ACCOUNT_ID/chats/CHAT_ID/messages \
  -H "Authorization: Bearer spc_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-7781" \
  -d '{ "text": "Thanks, see you at 3." }'

Start a WhatsApp chat

curl https://api.spacesos.com/v1/messaging/accounts/ACCOUNT_ID/chats \
  -H "Authorization: Bearer spc_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -d '{ "to": { "phone": "+15551234567" }, "text": "Your order is ready." }'

Every send needs an Idempotency-Key (8 to 128 letters, digits, dots, dashes or colons). Retrying with the same key never sends twice. If we cannot tell whether a message went out, the send is marked UNKNOWN and is not retried for you.

Limits

Every account stays inside the limits each channel allows, enforced on our side for every key and every agent, however it is prompted. New accounts start lower and warm up over four weeks. A customer can set a lower cap. The cap cannot go above these ceilings.

Channel	Between messages	New chats	Messages per day	First week
WhatsApp	A random 10 to 20 seconds, and 1 to 2 minutes before a new chat	5 an hour, 10 a day	400	No new chats for 24 hours, then 1 an hour and 3 a day
Instagram	15 seconds	10 an hour, 100 a day, shared with likes, comments, follows and views	150	4 an hour, 40 a day
LinkedIn	20 seconds	15 an hour, 100 a day	100	40 new chats and up to 40 invitations a day
Messenger	20 seconds	3 an hour, 8 a day	50	1 an hour, 3 a day
X	20 seconds	5 an hour, 20 a day	100	2 an hour, 6 a day

What each channel can do

Channel	Inbox and history	Download attachments	Send with attachments	Notes
WhatsApp	Yes	Yes	Yes	New chat uses a phone number
Instagram	Yes	Yes	Yes	New chat uses a username. Prefer a reply after the person has written.
Messenger	Yes	Yes	Yes	New chat uses the user id from an existing chat
LinkedIn	Yes	Yes	Yes	A normal message goes to a 1st-degree connection. Set inmail: true for an InMail. A connection request with a note is send_invitation.
X	Yes	Yes	Yes	New chat uses a username

On LinkedIn and Instagram you can list your posts, read comments and the replies under a comment, reply, react, and delete a comment you wrote. Instagram can also send the commenter a direct message. Comment replies have their own caps: 15 an hour and 100 a day on LinkedIn, and on Instagram they share the 10 an hour and 100 a day with likes, follows and new conversations. A direct message still uses the message caps. A routine can watch for a new comment or a keyword and reply, including from the snippets saved on that routine, and optionally send the direct message too. New comments are delivered as comment.received.

Channel	Your posts	Read and reply	React	Delete yours	Hide	Direct message the commenter
LinkedIn	Yes	Yes	Yes	Yes	No	No
Instagram	Yes	Yes	Like	Yes	No	Yes
Messenger	No	No	No	No	No	No. Page comments are not available on a Messenger account.
X	No	No	No	No	No	Replies and mentions are not available here.
WhatsApp	No	No	No	No	No	WhatsApp has no post comments.

Schedules and routines

Schedule a message for a local time, or save a routine. A routine can run every day, on a cron, on an interval, or when something happens: a new message, a keyword, an accepted connection, or no reply after a number of hours. The action can send a message, reply from snippets you saved on the routine, tag the chat, call your webhook, or email a short unread summary. You can pause, resume, or delete a routine and read its runs, including errors. Every one of those sends uses the same limits as a message you send by hand. A limit delays the job. A paused or restricted account stops it. This reduces the chance of a restriction. It cannot guarantee the platform will never restrict the account.

Keeping your accounts safe

Spaces reduces ban risk with enforced limits, warm-up, pacing and an automatic pause. It cannot guarantee the platform will not restrict the account. These limits apply to the API and to MCP. A 429 means nothing was sent. Wait retry_after_seconds, then retry with the same idempotency key. A send includes account_safety (remaining today, remaining this week, whether sending is paused, and why). New chats on a fresh account ramp up over four weeks. The same cold text cannot be sent to many people. If someone says stop, later sends to that chat are refused. If the account needs a checkpoint, new credentials, or is restricted, sending pauses until it is reconnected. You can read current usage with GET /messaging/usage.

LinkedIn actions

Action	Limit per account
Invitations	Free account: 100 a day and 150 a week. Premium, Sales Navigator or Recruiter: 100 a day and 200 a week. Spaced at random during working hours (22 a day on days 1 to 3, then 40, 60 and 85)
InMail	30 a day on a free account, 50 on Premium, Sales Navigator or Recruiter (about 800 a month)
Profile views	20 an hour, 100 a day (150 on Sales Navigator, 200 on Recruiter)
Searches	20 an hour, 100 a day (about a thousand results, or 2,500 on Sales Navigator and Recruiter)
Reading posts, comments and invitations	30 an hour, 100 a day
Comments	15 an hour, 100 a day
Reactions	20 an hour, 100 a day
Posts	100 a day, the same as other actions

Profile lookups on other channels: up to 100 a day on WhatsApp and Instagram (on Instagram inside its shared 100 actions), 40 on Messenger and 50 on X.

Every action warms up over four weeks on a new or reconnected account, and a reply to someone who wrote in is never held back by the daily limits. Over a limit you get 429 with a Retry-After header and retry_after_seconds in the body; nothing was sent. Agents should wait that long and try again. See your live numbers with GET /messaging/usage or on the dashboard.

Errors

Status	Meaning
401	Missing, wrong or revoked key
403	The key lacks the permission for this call; KEY_SUSPENDED means the key is paused, ACCOUNT_SUSPENDED means the workspace is suspended
404	Account, chat or recipient not found
409	Idempotency key reused for a different message, or a send in progress
429	Over a limit; wait retry_after_seconds (also in Retry-After)
502, 503	The channel is unavailable right now; nothing was sent, retry later

Every refusal carries code, error and doc_url, a page that explains the code and what to do. The common ones are on the limits page. To check one account, call GET /v1/messaging/accounts/{account_id}/health. Spotted a bug or a gap? POST /v1/feedback reaches the team. What changed: changelog.