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

# Codex

> Connect SocialAPI to OpenAI Codex (CLI, IDE extension, and ChatGPT desktop app) with one entry in ~/.codex/config.toml.

Connect SocialAPI to Codex and ask it to list your connected accounts, reply to comments, send direct messages (DMs), and publish posts. Codex reads MCP servers from `~/.codex/config.toml`. The Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share that file, so one entry gives every Codex session the SocialAPI tools. The server is `https://api.social-api.ai/mcp`.

## Prerequisites

* [Codex](https://developers.openai.com/codex) installed: CLI, IDE extension, or desktop app.
* A SocialAPI account with at least one connected account.
* For a machine without a browser: an [API key](/integrations/custom).

## Set up with the CLI

**1. Add the server**

```bash theme={null}
codex mcp add socialapi --url https://api.social-api.ai/mcp
```

Codex saves the server, detects that it uses OAuth 2.1 with PKCE, and opens your browser on the SocialAPI authorization page. Codex stores no API key and refreshes the token itself.

**2. Authorize**

Log in and click **Authorize**. The terminal prints `Successfully logged in to MCP server 'socialapi'`.

**3. Check the server**

```bash theme={null}
codex mcp list
```

`socialapi` is listed as `enabled` with its auth method. In the Codex TUI, type `/mcp` to see the connected servers and their tools.

To sign in again on a new machine or after a revoked session, run `codex mcp login socialapi`.

## Set up with the config file

**1. Add the entry**

`codex mcp add` writes this entry to `~/.codex/config.toml`. You can also add it by hand, globally or in a trusted project's `.codex/config.toml`:

```toml theme={null}
[mcp_servers.socialapi]
url = "https://api.social-api.ai/mcp"
```

**2. Authorize**

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

## Set up a headless machine with an API key

For CI jobs, containers, and any machine without a browser, skip OAuth and authenticate with an API key. Codex reads the key from an environment variable and sends it as `Authorization: Bearer`.

**1. Reference the variable**

```toml theme={null}
[mcp_servers.socialapi]
url = "https://api.social-api.ai/mcp"
bearer_token_env_var = "SOCAPI_KEY"
```

**2. Set the variable**

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

> [!WARNING]
>
> Keep the key in the environment or a secret manager. Never paste it into `config.toml` or commit it. To limit what the agent can do, create a [scoped API key](/guides/scoped-keys).

## Limit the tools

To give Codex fewer tools, list the ones to keep in `enabled_tools`, or the ones to hide in `disabled_tools`. Codex applies `disabled_tools` after `enabled_tools`:

```toml theme={null}
[mcp_servers.socialapi]
url = "https://api.social-api.ai/mcp"
disabled_tools = [
  "social_api_delete_post",
  "social_api_delete_comment",
  "social_api_disconnect_account",
  "social_api_revoke_key",
]
```

See [MCP tools reference](/integrations/tools) for every tool name.

## Try it

Ask Codex:

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

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

## Troubleshooting

> **The browser does not open**
>
> Codex prints the authorization URL (`Authorize socialapi by opening this URL in your browser`). Open it on the same machine: the callback goes to a local port that Codex listens on.

> **HTTP 401 with an API key**
>
> The variable named in `bearer_token_env_var` is not set in the shell that started Codex, or the key is revoked. Check the key in the [dashboard](https://app.social-api.ai/api-configuration?tab=keys).

> **Tools are missing in the IDE extension or desktop app**
>
> They read the same `~/.codex/config.toml`. Restart the app after you edit the file.

## Related

* [SocialAPI MCP server](/integrations/overview): the server URL and the other supported clients.
* [MCP tools reference](/integrations/tools): every tool Codex 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.