Archery MCP 2FA

A persistent patch that adds Archery TOTP two-factor authentication (2FA) support to @seaxlab/archery-mcp.

This project does not connect directly to the database, nor does it bypass Archery's permission, masking, rate-limiting, or audit mechanisms. It only extends the login flow so that Archery accounts with TOTP enabled can also complete authentication through the MCP service.

The current patch only applies to @seaxlab/archery-mcp@3.0.2. Before upgrading the upstream dependency, verify that the patch is still compatible and regenerate the patch file.

Features

• Automatically logs in at startup using the Archery account and password from the configuration.

• When TOTP verification is detected, prompts for a 6-digit verification code in an interactive terminal.

• When there is no interactive terminal, provides MCP tools to complete authentication.

• Reuses the same Archery session after successful authentication.

• The TOTP verification code is used only for the current request and is not written to the configuration file or metadata cache.

• Uses patch-package to automatically apply the patch after installing dependencies.

Related MCP server: auth-vault

Environment Requirements

• Node.js 24 or higher.

• npm 10 or higher.

• An accessible Archery service; the upstream package states support for Archery v1.8.5.

• An Archery account with TOTP enabled, or a regular account password.

Quick Start

1. Get the project and install dependencies

git clone <repository-url>
cd archery-mcp-2fa
npm ci

After npm ci completes, the postinstall script automatically applies the 2FA patch in patches/.

2. Prepare the configuration file

You can create the configuration based on the example provided by the upstream package:

mkdir -p ~/.config/archery-mcp
cp node_modules/@seaxlab/archery-mcp/config.example.toml \
  ~/.config/archery-mcp/pro.toml
chmod 600 ~/.config/archery-mcp/pro.toml

Edit ~/.config/archery-mcp/pro.toml and fill in at least the following:

env = "pro"

[server]
host = "127.0.0.1"
port = 3000

[archery]
base_url = "https://archery.example.com"
username = "mcp_service"
password = "replace-with-a-strong-password"

[query]
default_limit = 100
max_limit = 500

[cache]
enabled = true
ttl_seconds = 604800
exclude_instance_names = []
exclude_instance_ids = []

The configuration file contains plaintext passwords. Always restrict file permissions and do not commit real configuration to the repository.

For a full description of the configuration options, refer to node_modules/@seaxlab/archery-mcp/README.md and config.example.toml after installing the upstream project.

3. Start the service

Specify the configuration file via a command-line argument:

npm start -- --config ~/.config/archery-mcp/pro.toml

You can also use environment variables:

ARCHERY_MCP_CONFIG=~/.config/archery-mcp/pro.toml npm start

The default MCP address is:

http://127.0.0.1:3000/mcp

The health check address is:

http://127.0.0.1:3000/health

TOTP Authentication Flow

Interactive Terminal

If the account has TOTP enabled, the terminal will prompt at startup:

archery-mcp [env=pro] Archery requires TOTP authentication
请输入当前 6 位 TOTP 验证码:

Enter the verification code currently shown by your authenticator. After successful authentication, the service starts listening on the port:

archery-mcp [env=pro] TOTP authentication succeeded
archery-mcp [env=pro] listening on http://127.0.0.1:3000/mcp

If the verification code is invalid, you can retry directly. After the Archery session expires or the process restarts, you will need to verify again.

Non-interactive Terminal

When the service is started by a container, background task, or process manager without an interactive terminal, the service still starts and registers the following MCP tools:

Authentication steps:

1. Call archery_auth_status.

2. If it returns two_factor_required: true, ask the user to provide the 6-digit verification code currently shown by their authenticator.

3. Call archery_submit_otp with the parameter { "otp": "123456" }.

4. After confirming that it returns authenticated: true, call the query or SQL review tools.

Except for the two authentication tools above, the remaining MCP tools are identical to the upstream @seaxlab/archery-mcp.

MCP Client Configuration

Connect using an MCP client that supports Streamable HTTP:

{
  "mcpServers": {
    "archery": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Codex can be configured in ~/.codex/config.toml:

[mcp_servers.archery]
url = "http://127.0.0.1:3000/mcp"

Claude Code can be added via the command line:

claude mcp add --transport http archery http://127.0.0.1:3000/mcp

Project Structure

.
├── patches/
│   └── @seaxlab+archery-mcp+3.0.2.patch  # TOTP 支持补丁
├── package.json                           # 依赖和启动脚本
├── package-lock.json                      # 锁定依赖版本
└── README.md

Common Commands

Do not start directly with npx -y @seaxlab/archery-mcp@3.0.2, otherwise you will be running the official npm package without this project's 2FA patch.

Security Notes

• By default, it only listens on 127.0.0.1. The MCP HTTP endpoint itself has no authentication and should not be exposed directly to the public internet.

• For cross-machine access, add TLS, access authentication, and network access control at the reverse proxy layer.

• The Archery password is stored in the TOML configuration. Set chmod 600 and use a dedicated service account with least privilege.

• Do not commit real passwords, TOTP verification codes, session cookies, internal Archery addresses, or production configuration to repositories, Issues, or logs.

• TOTP is passed through MCP requests. When using a remote MCP client, make sure the communication link is trusted and encrypted.

Compatibility and Maintenance

The patch directly modifies the upstream package's build output, so upstream version changes may cause the patch to fail to apply or behave incompatibly. When upgrading, it is recommended to:

1. Update the @seaxlab/archery-mcp version in package.json.

2. Run npm install and check for patch conflicts.

3. Re-implement and verify the 2FA changes in node_modules/@seaxlab/archery-mcp.

4. Run npx patch-package @seaxlab/archery-mcp to generate a new patch.

5. Verify the authentication flow in both an interactive terminal and a non-interactive terminal.

Contributing

Issues and Pull Requests are welcome. Before submitting code, make sure it does not contain real accounts, passwords, verification codes, cookies, internal domain names, or other sensitive information.

Acknowledgments and Disclaimer

This project creates a patch based on the publicly released @seaxlab/archery-mcp package and is not an official project of Archery or the upstream package maintainers. The rights to Archery and related names belong to their respective owners.