Hermes Agent - SocialAPI

Connect SocialAPI to Hermes Agent 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 if you installed from PyPI.
A SocialAPI account with at least one connected account.
For a gateway with no browser: an API key.

Set up with OAuth

Add the server

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

mcp_servers:
  socialapi:
    url: "https://api.social-api.ai/mcp"
    auth: oauth

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.

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.

Store the key

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

SOCAPI_KEY=sapi_key_xxxxxxxxxxxxxxxx

Reference the key

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

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.

Limit the tools

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

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 for every tool name.

Try it

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

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.

SocialAPI MCP server: the server URL and the other supported clients.
MCP tools reference: every tool Hermes can call.
Custom MCP clients: API key setup in detail.
Reviews: read and reply to Google Business Profile reviews.

​Prerequisites

​Set up with OAuth

​Set up a headless gateway with an API key

​Limit the tools

​Try it

​Troubleshooting

​Related