Skip to main content
Glama

Sociality.io Social Media MCP

Connect a social account

social_account_connect
Use this when the user wants to add one of their social media accounts to their Sociality.io workspace, or when another tool answers with a no_channels or channel_token_expired action. Do not use it to post or to track a competitor.

Connect a social media account to the workspace, or reconnect one whose token expired, without leaving the conversation.

Call it with a `channel` to start: it returns a `connection_id` and a one-time `authorization_url`. Show the URL to the user as a link; they log in on the platform and every account they grant is saved: new ones are added to the workspace, up to the plan's page allowance, and ones already in the workspace get a fresh token. The link expires in 10 minutes and works once.

When the user says they are done, call it again with the same `channel` and the `connection_id` to read the result: `status` becomes `connected` or `failed`, with the `accounts` saved and, on failure, a `reason`. When the plan had no room for some or all of the granted accounts, `action_required` says which allowance ran out and where the user can change the plan; a new link will not help until they do. The response never contains an access token.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "channel": "<channel>"
    },
    "name": "social_account_connect"
  }
}

Input Schema

NameRequiredDescriptionDefault
channelYesThe social media channel to connect: facebook, x, instagram, youtube, linkedin or tiktok.
connection_idNoOmit to start a new connection and get a link. Pass the connection_id from an earlier call to read that connection's result once the user says they are done.

Output Schema

NameRequiredDescriptionDefault
reasonNoWhy the connection failed: authorization_denied, token_exchange_failed, not_authorized, authorization_url_failed, or page_limit_reached / page_change_limit_reached when the plan had no room for any granted account. Null unless status is failed.
statusNopending until the user finishes on the platform; then connected or failed; expired when the link lapsed.
channelNo
accountsNoEvery account the user granted that was saved: added to the workspace, or already there with a fresh token.
_envelopeYesVersioned response envelope metadata.
expires_atNoWhen the link stops working (ISO 8601). Present only when a new connection was started.
connection_idNoIdentifier of this connection. Pass it back to read the result.
action_requiredNoPresent when the plan turned granted accounts away. With status connected, accounts lists the ones that were saved and the rest were skipped; with status failed, none were. A new link will not change this: the user changes the plan at link, or removes a page, then connects again.
authorization_urlNoOne-time link for the user to open. Present only when a new connection was started.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedOutput schema / properties / action_required
      Added value: +{
      +  "description": "Present when the plan turned granted accounts away. With status connected, accounts lists the ones that were saved and the rest were skipped; with status failed, none were. A new link will not change this: the user changes the plan at link, or removes a page, then connects again.",
      +  "properties": {
      +    "action": {
      +      "description": "The action that unblocks this request. When it names a tool, call that tool from the conversation; otherwise the user takes it in Sociality.",
      +      "type": "string"
      +    },
      +    "code": {
      +      "description": "Machine-readable reason this request cannot be answered yet.",
      +      "enum": [
      +        "no_channels",
      +        "no_competitors",
      +        "channel_token_expired",
      +        "credits_exhausted",
      +        "page_change_limit_reached",
      +        "page_limit_reached",
      +        "data_retention_limited"
      +      ],
      +      "type": "string"
      +    },
      +    "link": {
      +      "description": "Sociality URL where the user takes that action themselves.",
      +      "type": "string"
      +    },
      +    "message": {
      +      "description": "User-facing explanation. Read this out to the user verbatim.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "message",
      +    "action",
      +    "link"
      +  ],
      +  "type": [
      +    "object",
      +    "null"
      +  ]
      +}
    • changedOutput schema / properties / reason / description
      Previous value: -"Why the connection failed: authorization_denied, token_exchange_failed, not_authorized or authorization_url_failed. Null unless status is failed."New value: +"Why the connection failed: authorization_denied, token_exchange_failed, not_authorized, authorization_url_failed, or page_limit_reached / page_change_limit_reached when the plan had no room for any granted account. Null unless status is failed."
  2. Added

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), the description discloses the two-phase handshake, that the authorization_url is one-time and expires in 10 minutes, that already-connected accounts get a fresh token, that new accounts are capped by the plan's page allowance, and that the response never contains an access token. The action_required / plan-limit escalation path is also explained, which the annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded with the when-to-use rule and exclusions before the mechanics, and each paragraph covers a distinct phase (start, complete, result). The opening clause of the second paragraph restates the first sentence's reconnect case, a small redundancy in an otherwise efficient structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-call, open-world OAuth-style tool, the description covers initiation, expiry, completion, failure reasons, and plan-limit dead ends. Although an output schema exists, the extra explanation of status/accounts/reason/action_required is genuinely useful for deciding the next step.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already describes both parameters, so the baseline is 3. The description goes further by framing them as a protocol: channel starts a connection and yields connection_id + authorization_url, while re-passing channel with connection_id reads the result. That sequencing meaning is slightly restated from the schema, which keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb+resource ("Connect a social media account to the workspace, or reconnect one whose token expired") and explicitly separates itself from posting and competitor tracking. An agent can distinguish it from social_accounts_list or social_competitors_create without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives both the positive trigger (user wants to add an account, or another tool returns no_channels / channel_token_expired) and explicit exclusions ("Do not use it to post or to track a competitor"). It also states the second-call condition ("When the user says they are done"), so the full invocation sequence is inferable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.