@authn8/mcp-server 1.1.1 → 1.1.3

package/README.md

@@ -1,34 +1,67 @@
 # @authn8/mcp-server
 
-MCP server that provides AI agents access to Authn8 2FA codes via PAT authentication.
+MCP server for [Authn8](https://authn8.com), shared 2FA for teams. It lets AI agents
+fetch TOTP codes for the 2FA accounts your team shares in Authn8, so an agent can
+finish a sign-in without anyone reading a code out of a phone. Every code it fetches
+is recorded in Authn8's access log with the name of the token that asked for it.
 
-## Prerequisites
+Listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as
+`io.github.authn8/mcp-server`.
 
-- An [Authn8](https://authn8.com) account
-- A Personal Access Token (PAT) created in the Authn8 dashboard
+## Requirements
 
-## Quick Start
+- An Authn8 business on a paid plan. MCP tokens are not available on the Free plan,
+  and a business's tokens stop working if its subscription ends.
+- An MCP token. Create one in Authn8 under **Settings → MCP Tokens**
+  ([how to create an MCP token](https://authn8.com/knowledge-base/how-to-create-an-mcp-token)).
+  Tokens start with `pat_`. A token only reaches the 2FA accounts its creator can
+  already access, and you can narrow it further to chosen groups and give it an
+  expiry date.
+- Node.js 18 or later, if you run the npm package. The hosted endpoint needs nothing
+  installed.
+
+## Two ways to connect
+
+| | Hosted endpoint | npm package |
+|---|---|---|
+| Install | None | `npx` runs it locally |
+| Transport | Streamable HTTP | stdio |
+| Address | `https://api.authn8.com/mcp` | `npx -y @authn8/mcp-server` |
+| Token | `Authorization: Bearer pat_...` header | `AUTHN8_API_KEY` environment variable |
+
+Both offer the same three tools: `list_accounts`, `get_otp` and `whoami`.
+
+## Hosted endpoint
+
+Point any MCP client that supports streamable HTTP at `https://api.authn8.com/mcp`
+and send your token in the `Authorization` header as `Bearer pat_your_token_here`.
+
+### Claude Code
 
 ```bash
-npx @authn8/mcp-server
+claude mcp add --transport http --scope user authn8 https://api.authn8.com/mcp \
+  --header "Authorization: Bearer pat_your_token_here"
 ```
 
-Set the `AUTHN8_API_KEY` environment variable to your PAT token.
+## npm package
 
-## Docker
+### Claude Code
 
 ```bash
-docker run -e AUTHN8_API_KEY=pat_xxx ghcr.io/authn8/mcp-server
+claude mcp add --env AUTHN8_API_KEY=pat_your_token_here --transport stdio --scope user authn8 \
+  -- npx -y @authn8/mcp-server
 ```
 
-## Configuration
+`--scope user` makes the server available in all your projects. Leave it out to add
+it to the current project only.
 
 ### Claude Desktop
 
-Add to your Claude Desktop configuration file:
+Open **Settings → Developer → Edit Config**, or edit the file directly:
 
-**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux:** `~/.config/Claude/claude_desktop_config.json`
 
 ```json
 {
@@ -44,12 +77,12 @@ Add to your Claude Desktop configuration file:
 }
 ```
 
-### Claude Code (CLI)
+Quit and restart Claude Desktop after saving.
 
-Add to your Claude Code configuration file:
+### Cursor
 
-**macOS:** `~/.claude.json`
-**Windows:** `%USERPROFILE%\.claude.json`
+Add this to `~/.cursor/mcp.json` for all projects, or to `.cursor/mcp.json` in a
+project:
 
 ```json
 {
@@ -65,32 +98,21 @@ Add to your Claude Code configuration file:
 }
 ```
 
-### Cursor
+### Other clients
 
-Add to your Cursor MCP settings:
+Run `npx -y @authn8/mcp-server` as a stdio server with `AUTHN8_API_KEY` set.
 
-```json
-{
-  "mcpServers": {
-    "authn8": {
-      "command": "npx",
-      "args": ["-y", "@authn8/mcp-server"],
-      "env": {
-        "AUTHN8_API_KEY": "pat_your_token_here"
-      }
-    }
-  }
-}
-```
-
-## Environment Variables
+### Environment variables
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `AUTHN8_API_KEY` | Yes | - | Your PAT token from Authn8 |
-| `AUTHN8_API_URL` | No | `https://api.authn8.com` | API endpoint URL |
+| `AUTHN8_API_KEY` | Yes | - | Your MCP token (`pat_...`) |
+| `AUTHN8_API_URL` | No | `https://api.authn8.com` | API base URL |
+
+On startup the server checks the token and prints the business name, token name,
+account count and expiry date to stderr. It exits if the token is missing or rejected.
 
-## Available Tools
+## Tools
 
 All tools declare an output schema and return `structuredContent` alongside the
 text block, so clients get typed results without re-parsing JSON out of text.
@@ -117,11 +139,12 @@ Returns all 2FA accounts accessible to this token.
 Generates a TOTP code for a specific account.
 
 **Parameters:**
-- `account_id` (string, optional) - UUID of the account
-- `account_name` (string, optional) - Name or issuer domain to search for (case-insensitive partial match)
+- `account_id` (string, optional): UUID of the account
+- `account_name` (string, optional): name or issuer domain to search for
+  (case-insensitive partial match)
 
-Provide either `account_id` or `account_name`. If multiple accounts match the
-name, the tool returns them in `multipleMatches` so you can retry with an
+Provide either `account_id` or `account_name`. If more than one account matches
+the name, the tool returns them in `multipleMatches` so you can retry with an
 `account_id`.
 
 **Example response:**
@@ -155,17 +178,19 @@ Returns information about the current token.
 **Example response:**
 ```json
 {
-  "tokenName": "MCP Server 2",
-  "businessName": "Bytecode Solutions",
+  "tokenName": "Claude Code",
+  "businessName": "Acme Ltd",
   "scopedGroups": [
-    { "id": "cfeba14a-e990-49e8-b6e5-61d63f7d68c8", "name": "HR" }
+    { "id": "cfeba14a-e990-49e8-b6e5-61d63f7d68c8", "name": "Engineering" }
   ],
-  "expiresAt": "2025-12-25T23:59:59Z",
-  "accountCount": 1
+  "expiresAt": "2027-06-30T23:59:59Z",
+  "accountCount": 12
 }
 ```
 
 ## Links
 
-- [Authn8](https://authn8.com) - Create an account and manage 2FA tokens
-- [GitHub Repository](https://github.com/authn8/mcp-server)
+- [Authn8](https://authn8.com): shared 2FA for teams
+- [How to create an MCP token](https://authn8.com/knowledge-base/how-to-create-an-mcp-token)
+- [GitHub repository](https://github.com/authn8/mcp-server)
+- [MCP Registry entry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.authn8/mcp-server)

package/dist/index.js

@@ -21,10 +21,32 @@ var Authn8Error = class extends Error {
 };
 var accountsCache = null;
 var CACHE_TTL_MS = 60 * 1e3;
+async function readApiError(response) {
+  try {
+    const body = await response.json();
+    if (Array.isArray(body.errors)) {
+      const messages = body.errors.filter(
+        (error) => typeof error === "string" && error.length > 0
+      );
+      if (messages.length > 0) {
+        return messages.join(" ");
+      }
+    }
+    if (typeof body.detail === "string" && body.detail.length > 0) {
+      return body.detail;
+    }
+    if (typeof body.title === "string" && body.title.length > 0) {
+      return body.title;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
 async function apiRequest(endpoint, method = "GET") {
   if (!API_KEY) {
     throw new Authn8Error(
-      "AUTHN8_API_KEY environment variable is not set. Please set it to your PAT token from the Authn8 dashboard."
+      "AUTHN8_API_KEY environment variable is not set. Set it to an MCP token from Settings > MCP Tokens in Authn8."
     );
   }
   const url = `${API_URL}${endpoint}`;
@@ -39,10 +61,16 @@ async function apiRequest(endpoint, method = "GET") {
   if (!response.ok) {
     if (response.status === 401) {
       throw new Authn8Error(
-        "Token is invalid or expired. Please check your token in the Authn8 dashboard.",
+        "Token is invalid, expired or revoked. Check it under Settings > MCP Tokens in Authn8.",
         401
       );
     }
+    if (response.status !== 429) {
+      const apiMessage = await readApiError(response);
+      if (apiMessage) {
+        throw new Authn8Error(apiMessage, response.status);
+      }
+    }
     if (response.status === 403) {
       throw new Authn8Error(
         "Token does not have permission to access this resource.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@authn8/mcp-server",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "MCP server for Authn8 2FA code access",
   "mcpName": "io.github.authn8/mcp-server",
   "type": "module",