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

# Hermes Agent

> Connect SocialAPI to Nous Research's Hermes Agent with one mcp_servers entry, then publish and reply from any chat Hermes is connected to.

Connect SocialAPI to [Hermes Agent](https://hermes-agent.nousresearch.com) and ask it to list your connected accounts, reply to comments, send direct messages (DMs), and publish posts from `hermes chat` or from any messaging channel your Hermes gateway runs. Hermes reads MCP servers from `~/.hermes/config.yaml`. The server is `https://api.social-api.ai/mcp`.

## Prerequisites

* Hermes Agent installed with MCP support. The standard install includes it: see [Troubleshooting](#troubleshooting) if you installed from PyPI.
* 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**

Add this to `~/.hermes/config.yaml`:

```yaml theme={null}
mcp_servers:
  socialapi:
    url: "https://api.social-api.ai/mcp"
    auth: oauth
```

**2. Sign in**

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

Hermes opens your browser on the SocialAPI authorization page. Log in and click **Authorize**. When the callback arrives, Hermes prints `Authenticated` with the number of tools available. Hermes caches the token in `~/.hermes/mcp-tokens/socialapi.json` and refreshes it automatically.

If Hermes runs on a remote host, the browser callback cannot reach it. Paste the redirect URL into the prompt that `hermes mcp login` shows, or authorize from Hermes Desktop, which relays the callback.

**3. Start using it**

Start a new session with `hermes chat`, or type `/reload-mcp` in a running one. A running messaging gateway (`hermes gateway run`) watches `config.yaml` and connects the new server, so the same tools work from Telegram, Discord, or any other channel routed to Hermes.

Hermes registers the tools with an `mcp_socialapi_` prefix, for example `mcp_socialapi_social_api_list_accounts`. You never need to call a tool by name.

## Set up a headless gateway with an API key

For a gateway with no browser, authenticate with an API key instead of OAuth.

**1. Store the key**

Put the key in `~/.hermes/.env`:

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

**2. Reference the key**

Reference it from `config.yaml`, without `auth: oauth`:

```yaml theme={null}
mcp_servers:
  socialapi:
    url: "https://api.social-api.ai/mcp"
    headers:
      Authorization: "Bearer ${SOCAPI_KEY}"
```

Hermes substitutes `${SOCAPI_KEY}` when it runs, so the key never sits in `config.yaml`. To limit what the agent can do, create a [scoped API key](/guides/scoped-keys).

## Limit the tools

Keep a subset of tools with `tools.include`, or hide some with `tools.exclude`:

```yaml theme={null}
mcp_servers:
  socialapi:
    url: "https://api.social-api.ai/mcp"
    auth: oauth
    tools:
      exclude:
        - social_api_delete_post
        - social_api_delete_comment
        - social_api_disconnect_account
        - social_api_revoke_key
```

You can also switch tools on and off interactively with `hermes mcp configure socialapi`. See [MCP tools reference](/integrations/tools) for every tool name.

## Try it

Run `hermes mcp test socialapi` to check that Hermes connects, authenticates, and counts the tools. Then ask Hermes:

```text theme={null}
Reply to every unanswered Google review from this week with a short thank-you.
```

Hermes lists your Google Business Profile reviews, finds the ones without a reply, and posts a reply to each.

## Troubleshooting

> **mcp.client.streamable\_http is not available**
>
> Hermes was installed without its MCP dependencies, for example with `uv tool install hermes-agent`. Reinstall with the extra: `uv tool install --force 'hermes-agent[mcp]'`.

> **non-interactive environment and no cached tokens found**
>
> The first OAuth sign-in needs a terminal. Run `hermes mcp login socialapi` interactively once, or use the API key setup.

> **401 Unauthorized**
>
> The token or key is wrong or revoked. Run `hermes mcp login socialapi` again, or 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 Hermes can call.
* [Custom MCP clients](/integrations/custom): API key setup in detail.
* [Reviews](/guides/reviews): read and reply to Google Business Profile reviews.


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