Where should the Somvia token be stored?

Store it as an environment variable in a private file such as ~/.hermes/.env, restrict the file permissions, and reference the variable from config.yaml instead of committing the token.

Connect Hermes Agent to Apple Health

Q: Does Hermes Agent support remote MCP servers?

Yes. Hermes Agent supports URL-based HTTP MCP servers and custom request headers. Somvia uses a Streamable HTTP endpoint with a bearer Authorization header for the headless path.

Q: Why use a Somvia token instead of browser OAuth in Hermes?

The app-issued bearer token works in headless or unattended Hermes deployments without an interactive browser sign-in. It can be refreshed from Somvia if it is exposed.

Why Hermes and Somvia fit together

Hermes Agent supports remote HTTP MCP servers with custom headers. Somvia exposes Apple Health as that standard server, so Hermes can discover the health tools at startup and call them only when a question requires personal data.

The bearer-token path is especially useful for a Hermes gateway running on a server, a home lab, or another unattended machine. The iPhone handles HealthKit permissions and syncing; Hermes does not need direct access to the phone or an Apple Health export.

Hermes' current MCP documentation defines URL-based servers under mcp_servers, accepts an Authorization header, and supports environment-variable substitution in headers. See the official Hermes MCP guide.

Connect Hermes to Somvia

Install, authorize, and sync

Install Somvia on your iPhone, sign in with Apple, activate Pro, choose the Health categories and history window you want, then open Connection from Today or Settings, turn on Sync to the Somvia server, and let the first sync finish. Upload is off by default, and Hermes can only retrieve data that has reached your Somvia account.
Copy your private connection token

Open Somvia's agent connection screen and copy the token beginning with som_. This token grants read access to the data you selected, so treat it like a password.

Store the token outside the YAML

Add the token to Hermes' private environment file:

# ~/.hermes/.env
SOMVIA_ACCESS_TOKEN=som_your_private_token_here

chmod 600 ~/.hermes/.env

Add the remote MCP server

Add this block to ~/.hermes/config.yaml. Keep any existing mcp_servers entries alongside it.

mcp_servers:
  somvia:
    url: "https://somvia.app/mcp"
    headers:
      Authorization: "Bearer ${SOMVIA_ACCESS_TOKEN}"
    enabled: true
    timeout: 120
    connect_timeout: 60

Reload and ask a real question

Restart Hermes or run /reload-mcp inside the Hermes CLI. Then ask a question that requires data, such as “Compare my last four interval runs.” A successful answer should cause Hermes to call one or more Somvia health tools.

If Hermes reports no tools: verify the token contains no quotes or spaces, confirm the initial Somvia sync completed, and check that the environment variable is available to the Hermes process. After editing the config, reload MCP connections.

What Hermes can retrieve

Question	Somvia tool path
“How did my sleep change this week?”	Daily summary or sleep-stage tools over a bounded date range
“List my runs this month.”	Workout list filtered by local date and activity
“Compare the intervals in these runs.”	Workout summaries and splits, followed by a detail series if needed
“Did pace improve at the same effort?”	Speed or pace context combined with heart-rate, power, or cadence series

Hermes prefixes discovered MCP tool names with the server name. The exact visible name can vary by Hermes version, but the underlying Somvia operations remain read-only.

Token security and rotation

Never commit the som_ token to a repository or paste it into public logs.
Keep it in ~/.hermes/.env or the secret store used by your gateway service.
If the token is exposed, refresh it in Somvia Settings. The previous token stops working, so update every connected headless agent.
Somvia stores only a SHA-256 hash of the token server-side; the plain token is shown to you for connection use.

Useful first prompts

Use Somvia to summarize my sleep stages and resting heart rate over the last seven days.
Compare my three most recent runs by pace, average heart rate, and available splits.
For my latest interval session, inspect the heart-rate and speed series and describe recovery between work reps.

Somvia supplies data, not diagnosis. Hermes' answer depends on its model, your prompt, the data Apple Health recorded, and what you chose to sync.

Frequently asked questions

Does Hermes Agent support remote MCP servers?

Yes. Hermes supports URL-based HTTP MCP servers and custom request headers. Somvia uses this path with a bearer Authorization header.

Why use a token instead of browser OAuth?

The app-issued token works in headless or unattended Hermes deployments without an interactive browser sign-in. If it is exposed, you can refresh it from Somvia.

Where should the token be stored?

Use a private environment file such as ~/.hermes/.env or your service's secret store. Reference the environment variable from YAML instead of committing the token.

Give Hermes your Apple Health history.

Why Hermes and Somvia fit together

Connect Hermes to Somvia

Install, authorize, and sync

Copy your private connection token