> ## Documentation Index
> Fetch the complete documentation index at: https://docs.social-api.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Base URL: https://api.social-api.ai/v1. Send your API key in the Authorization header: Authorization: Bearer <your API key>.
> Every error response from /v1 is JSON: { "error": { "code", "message", "meta" (optional) }, "request_id" }. Branch on error.code; use error.message only for logs.
> A 429 response carries a Retry-After header, in seconds, when the limit has a known wait.
> Paginated list endpoints return next_cursor, at the top level or inside pagination (see /guides/pagination). Pass it as the cursor query parameter to get the next page. An absent or empty next_cursor means you have the last page.
> Treat every ID as an opaque string: do not parse it or assume a format.
> Support differs by platform and by operation. Check /platforms/overview before assuming an operation works on a platform. An unsupported operation returns 501 with error.code resource.not_supported.

# OpenClaw

> Connect SocialAPI to OpenClaw with one openclaw mcp add, so the agent behind every routed channel can publish and reply.

Connect SocialAPI to [OpenClaw](https://docs.openclaw.ai) so the agents behind every channel you route through the OpenClaw gateway can list your connected accounts, reply to comments, send direct messages (DMs), and publish posts. OpenClaw keeps its MCP servers in `~/.openclaw/openclaw.json` under `mcp.servers`. The server is `https://api.social-api.ai/mcp`.

## Prerequisites

* OpenClaw installed (`npm i -g openclaw`).
* A SocialAPI account with at least one connected account.
* For a gateway with no browser: an [API key](/integrations/custom).

## Set up with OAuth

**1. Add the server**

```bash theme={null}
openclaw mcp add socialapi \
  --url https://api.social-api.ai/mcp \
  --transport streamable-http \
  --auth oauth
```

This saves the entry to `~/.openclaw/openclaw.json`:

```json theme={null}
{
  "mcp": {
    "servers": {
      "socialapi": {
        "url": "https://api.social-api.ai/mcp",
        "transport": "streamable-http",
        "auth": "oauth"
      }
    }
  }
}
```

Set `transport` to `streamable-http`. When you omit it, OpenClaw uses SSE.

**2. Sign in**

```bash theme={null}
openclaw mcp login socialapi
```

OpenClaw prints an authorization URL and waits for the browser callback on `127.0.0.1:8989`. Open the URL, log in to SocialAPI, and click **Authorize**. The terminal prints `MCP OAuth credentials saved for "socialapi"`.

If the gateway runs on another machine and the callback cannot reach it, authorize in your browser, copy the `code` from the redirect URL, and finish with:

```bash theme={null}
openclaw mcp login socialapi --code <code>
```

**3. Check the server**

```bash theme={null}
openclaw mcp probe socialapi
```

OpenClaw connects and reports the number of tools. If the gateway is already running, `openclaw mcp reload` picks up the new server without a restart.

## Choose shared or per-sender accounts

By default, the credentials from `openclaw mcp login` are shared: every channel acts on the one SocialAPI account you authorized. Use this for a personal assistant or a team bot.

To let each person who messages the agent connect their own SocialAPI account, set `oauth.identity` to `per-requester` and give the gateway a public HTTPS origin for the callback:

```json theme={null}
{
  "gateway": {
    "publicOrigin": "https://gateway.example.com"
  },
  "mcp": {
    "servers": {
      "socialapi": {
        "url": "https://api.social-api.ai/mcp",
        "transport": "streamable-http",
        "auth": "oauth",
        "oauth": { "identity": "per-requester" }
      }
    }
  }
}
```

The first time a sender calls a SocialAPI tool, OpenClaw replies with a sign-in link for that sender.

## Set up a headless gateway with an API key

OpenClaw ignores a static `Authorization` header while `auth` is `oauth`, so save the server without `auth`:

**1. Set the variable**

```bash theme={null}
export SOCAPI_KEY=sapi_key_xxxxxxxxxxxxxxxx
```

**2. Save the server**

```bash theme={null}
openclaw mcp set socialapi '{"url":"https://api.social-api.ai/mcp","transport":"streamable-http","headers":{"Authorization":"Bearer ${SOCAPI_KEY}"}}'
```

OpenClaw resolves `${SOCAPI_KEY}` from the environment the gateway runs in, so the key never sits in `openclaw.json`. To limit what the agent can do, create a [scoped API key](/guides/scoped-keys).

## Limit the tools

Hide the tools that a channel agent must never call:

```bash theme={null}
openclaw mcp tools socialapi --exclude 'social_api_delete_*,social_api_disconnect_account,social_api_revoke_key'
```

Use `--include` to keep only a subset instead, and `--clear` to remove the filter. See [MCP tools reference](/integrations/tools) for every tool name.

## Try it

Send the agent a message on any routed channel:

```text theme={null}
List my connected social accounts
```

The agent calls `social_api_list_accounts` and answers with your connected accounts and their platforms.

## Troubleshooting

> **listen EADDRINUSE: address already in use 127.0.0.1:8989**
>
> Another `openclaw mcp login` is still waiting. Stop it, or finish with `--code <code>` as shown above.

> **requires OAuth authorization**
>
> The server is saved but not signed in. Run `openclaw mcp login socialapi`.

> **Streamable HTTP error with an API key**
>
> The key is wrong or revoked, or the variable is not set where the gateway runs. Check the key in the [dashboard](https://app.social-api.ai/api-configuration?tab=keys).

## Related

* [SocialAPI MCP server](/integrations/overview): the server URL and the other supported clients.
* [MCP tools reference](/integrations/tools): every tool the agent can call.
* [Custom MCP clients](/integrations/custom): API key setup in detail.
* [OAuth for MCP clients](/integrations/oauth): how the sign-in works.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.