> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes

> Connect Hermes Agent to your data in Nekt using the MCP Server with bearer token authentication.

[Hermes Agent](https://github.com/NousResearch/hermes-agent) by Nous Research is an AI agent with a native MCP client. When you add the Nekt MCP Server to its configuration, Hermes connects on startup, discovers every available tool, and registers each one with the `mcp_nekt_*` prefix across all its platforms (CLI, Telegram, Discord, Slack, and others).

Hermes is the **agent**, while the underlying **LLM** is configured separately — you can run it on any model, including DeepSeek, OpenAI, or others. Nekt's MCP Server exposes the tools; Hermes passes their schemas to whichever model you've configured, and the model decides which tools to call.

Once connected, you can simply ask *"what was the revenue per customer last month?"* and Hermes uses the Nekt tools to discover the right tables, generate SQL, run the query, and answer.

<Info>Requires a **paid Nekt plan** (for MCP Server access), **Hermes Agent** installed, and the **`mcp` Python package** (`pip install mcp`). Without the `mcp` package, Hermes silently ignores the `mcp_servers` section.</Info>

## 1. Activate your MCP Server

The connection is made by activating the MCP Server in your workspace. Check [this guide](/mcp-server/setup) for instructions.

## 2. Get your endpoint and token

Go to **Integrations > MCP Server** in the Nekt platform. You'll need two values:

* **Endpoint** — the MCP server URL displayed at the top of the page
* **Token** — a bearer token created in the **MCP Tokens** section

If you don't have a token yet, create one. You can scope it to specific tables or grant full access.

<Note>
  Tokens created manually can be scoped to specific tables for fine-grained access control. Tokens grant Hermes access only to the tables associated with that token.
</Note>

## 3. Connect Hermes to Nekt

<Steps>
  <Step title="Store your credentials">
    Keep secrets out of the config file by adding them to `~/.hermes/.env`:

    ```bash theme={null}
    NEKT_MCP_URL=https://your-endpoint.mcp.nekt.ai
    NEKT_MCP_TOKEN=your-token-here
    ```

    Replace the values with the endpoint and token from the Nekt platform.
  </Step>

  <Step title="Add the Nekt MCP server">
    Open `~/.hermes/config.yaml` and add the server under the `mcp_servers` key. Hermes interpolates `${VAR_NAME}` from your `.env`:

    ```yaml theme={null}
    mcp_servers:
      nekt:
        url: ${NEKT_MCP_URL}
        headers:
          Authorization: "Bearer ${NEKT_MCP_TOKEN}"
        timeout: 120          # seconds per tool call (default: 120)
        connect_timeout: 60   # seconds for the initial connection (default: 60)
    ```

    The Nekt MCP Server uses HTTP transport with a bearer token, which Hermes supports natively. Increase `timeout` (for example, to `300`) if you run heavy queries that return large result sets.
  </Step>

  <Step title="Apply the configuration">
    Reload Hermes so it picks up the new server:

    * **CLI** — exit and start again (`hermes`)
    * **Gateway** (Telegram, Discord, etc.) — send `/restart` in the chat
    * **Inline** — run `/reload-mcp` to reload without leaving the session (a full restart is more reliable)
  </Step>
</Steps>

<Warning>
  Hermes does not support the interactive OAuth 2.1 flow (browser redirect) for Nekt. Use bearer token authentication as described above. The token does not refresh automatically — when it expires, update `NEKT_MCP_TOKEN` in `.env` and restart Hermes.
</Warning>

<Note>
  Hermes profiles (`default`, `analista`, etc.) do **not** inherit the `mcp_servers` section. If you use profiles, replicate the configuration in each profile's `config.yaml` (e.g. `~/.hermes/profiles/analista/config.yaml`).
</Note>

## 4. Verify the connection

Each Nekt tool is registered with the `mcp_nekt_` prefix. Confirm the connection from the Hermes chat:

```
Use mcp_nekt_list_layers()
```

Or from the CLI:

```bash theme={null}
hermes mcp test nekt
```

You should see the tools provided by the Nekt MCP Server. You can learn more about them [here](/mcp-server/tools).

***

## 5. Explore your data

Once connected, ask Hermes a question about your data. For example:

```
What were the top 5 customers by revenue this month?
```

Hermes orchestrates the Nekt tools in sequence — discovering relevant tables (`mcp_nekt_get_relevant_tables_ddl`), generating SQL (`mcp_nekt_generate_sql`), executing it (`mcp_nekt_execute_sql`), and interpreting the results — then answers in natural language, without you writing a line of SQL.

<Check>
  We'd love to know what you're building with Nekt! Share your projects with us through any of our communication channels.
</Check>

***

## Troubleshooting

| Symptom                                    | Likely cause                        | Action                                                                    |
| ------------------------------------------ | ----------------------------------- | ------------------------------------------------------------------------- |
| No `mcp_nekt_*` tools appear               | `mcp` package not installed         | `pip install mcp`, then restart                                           |
| `"No MCP servers configured"`              | Empty or mis-indented `mcp_servers` | Check `config.yaml`                                                       |
| `401 Unauthorized`                         | Expired or invalid token            | Renew `NEKT_MCP_TOKEN` and restart                                        |
| Connection timeout                         | Endpoint unreachable                | Test with `curl -H "Authorization: Bearer $NEKT_MCP_TOKEN" $NEKT_MCP_URL` |
| Works in `default` but not another profile | Profiles don't inherit MCP servers  | Replicate `mcp_servers` in that profile                                   |

***

## Privacy & Security

Your data privacy is a core principle of the Nekt platform.

When you connect Hermes to Nekt through the MCP Server, Hermes does not receive direct database credentials or unrestricted access to your infrastructure. Instead, Hermes interacts with your data exclusively through the secure tools exposed by the Nekt MCP Server, which act as a controlled gateway to the Nekt API. These tools enforce the same authentication, authorization, and permission rules used throughout the Nekt platform.

Access is scoped using tokens and user permissions, meaning Hermes can only access the tables and actions explicitly allowed by the token you configured. This architecture ensures that all queries, analysis, and data interactions remain governed, auditable, and restricted to your workspace permissions.

When using Hermes with a third-party model such as DeepSeek or OpenAI, your interactions are also subject to that provider's privacy policies. We recommend reviewing the relevant provider's documentation to understand their data handling practices and selecting the configuration that best aligns with your organization's security requirements.

***

## Need help?

Contact our support team if you encounter issues during setup.