> ## 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. Authenticated responses can carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset for the per-minute request budget your SocialAPI account shares across every API key (see /guides/rate-limits).
> 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.

# Custom MCP clients

> Connect any MCP client to the SocialAPI MCP server with an API key for headless agents, server-side scripts, and CI jobs.

Connect any MCP client to SocialAPI's MCP server at `https://api.social-api.ai/mcp` with an API key sent on the `Authorization: Bearer` header. Use this setup when your client does not implement OAuth 2.1, or when the agent runs without a browser: on a server, in a container, in a CI job, or on a schedule.

## Prerequisites

* A SocialAPI account with at least one connected account.
* An API key from the [dashboard](https://app.social-api.ai/api-configuration?tab=keys) or from `POST /v1/keys`. A key starts with `sapi_key_`. See [Authentication](https://docs.social-api.ai/guides/authentication.md).

> [!WARNING]
>
> An API key is a long-lived credential. Keep it in a secret manager or an environment variable, never in source control.

## Set up the config file

**1. Add the server**

Most MCP clients accept a custom `Authorization` header in the server config. Set it to your API key prefixed with `Bearer `:

```json theme={null}
{
  "mcpServers": {
    "SocialAPI": {
      "url": "https://api.social-api.ai/mcp",
      "headers": {
        "Authorization": "Bearer sapi_key_xxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

**2. Match your client's field name**

The field name differs by client. Some clients use `headers`, others use `requestInit.headers` or a top-level `auth` block. Check your client's MCP documentation.

## Call the server over HTTP

The MCP endpoint speaks Streamable HTTP. Send each tool call as a JSON-RPC message in a `POST` request. The `Authorization` header is required on every request, and API key authentication has no `/oauth/authorize` redirect and no PKCE exchange.

```bash theme={null}
curl https://api.social-api.ai/mcp \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'
```

The response lists every tool with its input schema. Tool names start with `social_api_`: see [MCP tools reference](https://docs.social-api.ai/integrations/tools.md).

## Limit what the agent can do

A full-access API key can run every tool. To restrict an agent to some operations or some brands, issue it a [scoped API key](https://docs.social-api.ai/guides/scoped-keys.md). A tool outside the key's scopes returns `auth.insufficient_scope`, with the missing scope in `required_scope`. `required_scope` is absent for tools that need a full-access key: see [Scoped API keys](https://docs.social-api.ai/guides/scoped-keys.md). Plan allowances and platform support apply to a tool exactly as they do to its REST equivalent.

## Rotate a key

Rotate a key with `POST /v1/keys/{id}/rotate`. It returns a new secret for the same key, keeps its scopes and brands, and ends the old secret at once. Update the agent's config with the new secret. See [Authentication](https://docs.social-api.ai/guides/authentication.md#rotate-a-key).

To revoke a key instead, use `DELETE /v1/keys/{id}` or the dashboard. A tool call that uses a revoked key returns HTTP 401.

## Try it

Run the `tools/list` request above. A successful response is HTTP 200 and lists tools such as `social_api_list_accounts`. Then call that tool:

```bash theme={null}
curl https://api.social-api.ai/mcp \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": { "name": "social_api_list_accounts", "arguments": {} }
  }'
```

The result lists your connected accounts.

## Troubleshooting

> **HTTP 401 with invalid or inactive API key**
>
> A wrong, revoked, or rotated `sapi_key_` key returns `{"error": "invalid or inactive API key"}`. A token without the `sapi_key_` prefix that is not a valid OAuth 2.1 access token returns `{"error": "invalid token"}`. Check the key in the [dashboard](https://app.social-api.ai/api-configuration?tab=keys).

> **HTTP 401 with missing Authorization header**
>
> Your client is not sending the header. Check the field name in its MCP config, and check that the header reaches the server through any proxy in between.

> **HTTP 402 on every call**
>
> Every MCP request returns HTTP 402 `billing.past_due` until the invoice is paid. See [Plans](https://docs.social-api.ai/guides/plans.md#past-due-accounts) for how access returns.

> **A tool is not found**
>
> Run `tools/list` to read the exact tool names. Every name starts with `social_api_`: see [MCP tools reference](https://docs.social-api.ai/integrations/tools.md).

## Related

* [SocialAPI MCP server](https://docs.social-api.ai/integrations/overview.md): the server URL and the supported clients.
* [MCP tools reference](https://docs.social-api.ai/integrations/tools.md): every tool and the endpoint it runs.
* [Authentication](https://docs.social-api.ai/guides/authentication.md): create, rotate, and revoke API keys.
* [Scoped API keys](https://docs.social-api.ai/guides/scoped-keys.md): restrict an agent to some scopes and brands.
* [Errors](https://docs.social-api.ai/guides/errors.md): every error code a tool can return.


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