How to use with Hermes

Connect Hermes Agent to your Awaken account through MCP, or install the Awaken skill for guided workflows.

Before you begin

Install and configure Hermes Agent first. If you are new to Hermes, follow the official installation guide.

Awaken API access is currently in beta and requires a Dolphin or Whale plan. If the API Keys page says access is not enabled for your client, email beta@awaken.tax to request it.

Hermes supports remote HTTP MCP servers

Hermes reads MCP servers from ~/.hermes/config.yaml, discovers their tools when it starts, and makes them available alongside its built-in tools.

Create an API key

Keep the key private

Store the key in Hermes' private .env file, not directly in config.yaml or a chat. If it is exposed, expired, or no longer needed, revoke it from Settings → API Keys and create a replacement.

1. Open API Keys

In the Awaken workspace you want to connect, open Settings → API Keys and select Create API Key.

2. Choose access

Give the key a recognizable name, choose Read for analysis or Read + Write only when Hermes should edit data, and optionally set an expiration.

3. Copy the secret and client ID

Copy the awaken_… secret when it appears; for security, it cannot be viewed again. Also copy the client ID shown on the API Keys page. The key is scoped to that client only.

Save the Awaken credentials

Add the API key and client ID to ~/.hermes/.env. Hermes resolves these variables when it connects to the MCP server.

Hermes secrets

# ~/.hermes/.env
AWAKEN_API_KEY=YOUR_API_KEY
AWAKEN_CLIENT_ID=YOUR_CLIENT_ID

Add the Awaken MCP server

Add the following entry to ~/.hermes/config.yaml. If the file already contains an mcp_servers section, add only the awaken entry beneath it.

Hermes MCP configuration

# Add to ~/.hermes/config.yaml
mcp_servers:
  awaken:
    url: "https://mcp.awaken.tax/mcp"
    headers:
      Authorization: "Bearer ${AWAKEN_API_KEY}"
      x-client-id: "${AWAKEN_CLIENT_ID}"
    enabled: true

Test and use the connection

Test the server with hermes mcp test awaken, then start Hermes with hermes chat. If Hermes is already open, run /reload-mcp. Use hermes mcp configure awaken when you want to choose which Awaken tools are enabled.

Review

Show my largest taxable events this year and flag anything missing cost basis.

Clean up

Find my unreviewed transactions, explain the likely labels, and ask before changing anything.

Reports

Generate my Form 8949 report for 2025 and tell me when it is ready.

bash

hermes mcp test awaken
hermes chat

Prefer the Awaken skill?

How to use the Awaken skill

Install Awaken directly as a Hermes skill for guided API workflows without configuring MCP.

Hermes documentation

For configuration details and troubleshooting, see Hermes' official MCP guide and MCP configuration reference.