Custom MCP clients

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 or from POST /v1/keys. A key starts with sapi_key_. See Authentication.

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

Add the server

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

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

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.

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.

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. 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. 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. 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:

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.

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 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.

SocialAPI MCP server: the server URL and the supported clients.
MCP tools reference: every tool and the endpoint it runs.
Authentication: create, rotate, and revoke API keys.
Scoped API keys: restrict an agent to some scopes and brands.
Errors: every error code a tool can return.

​Prerequisites

​Set up the config file

​Call the server over HTTP

​Limit what the agent can do

​Rotate a key

​Try it

​Troubleshooting

​Related

Prerequisites

Set up the config file

Call the server over HTTP

Limit what the agent can do

Rotate a key

Try it

Troubleshooting

Related