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

# MCP Authentication

> Authenticate MCP clients with a personal access token or via OAuth.

MCP clients authenticate to HERO with either a **personal access token** (works everywhere) or **OAuth** (when supported by your client). Pick the tab that matches your setup.

<Tabs>
  <Tab title="Personal access token">
    Works with every stdio MCP client. Paste the token into your client's config.

    <Steps>
      <Step title="Open MCP Settings">
        Sign in at [HERO](https://app.myhero.so) and go to **[MCP Settings](https://app.myhero.so/#/settings/mcp-tokens "https://app.myhero.so/#/settings/mcp-tokens")**.
      </Step>

      <Step title="Generate a token">
        Click **Generate New Token**. Copy the `hero_at_*` value — it's shown once.
      </Step>

      <Step title="Paste into your client's config">
        Stdio MCP clients receive the token via the `HERO_API_KEY` environment variable in their server entry:

        ```json theme={null}
        {
          "mcpServers": {
            "hero": {
              "command": "npx",
              "args": ["-y", "@myhero/mcp-server"],
              "env": { "HERO_API_KEY": "hero_at_..." }
            }
          }
        }
        ```

        Or set `HERO_API_KEY` in your shell/application environment directly.
      </Step>
    </Steps>
  </Tab>

  <Tab title="OAuth">
    Skip the manual token — `@myhero/mcp-server` signs you in automatically the first time it needs credentials. No paste, no rotate, no shell setup. If `HERO_API_KEY` is not set, the OAuth flow triggers on the next tool call.

    <Steps>
      <Step title="Browser opens automatically">
        The MCP server starts a short-lived listener on a free localhost port and launches your default browser at HERO's sign-in page. <br />
        You don't run anything yourself.
      </Step>

      <Step title="Sign in and approve">
        Sign in to HERO if you aren't already, then approve access for the `hero-mcp` client.
      </Step>

      <Step title="Close the tab">
        HERO redirects back to the localhost listener and the page shows **"Login successful! You can close this tab."** That's the whole user-facing flow.
      </Step>

      <Step title="Done — credentials saved">
        The MCP server exchanges the authorization code for an access token (PKCE), writes it to `~/.hero/credentials.json` with mode `0600`, and refreshes automatically before expiry. <br />
        You won't be prompted again unless the refresh token is revoked or you delete that file.
      </Step>
    </Steps>

    The server hits HERO's standard OAuth endpoints under the hood — included for transparency, you don't call them directly:

    | Endpoint          | URL                                     |
    | ----------------- | --------------------------------------- |
    | Authorization URL | `https://app.myhero.so/oauth/authorize` |
    | Token URL         | `https://app.myhero.so/oauth/token`     |
  </Tab>
</Tabs>