BoomTax README

BoomTax MCP Server

Read-only BoomTax filing tools for Claude, ChatGPT, Codex, Cursor, Windsurf, VS Code Copilot, and other Model Context Protocol clients.

The hosted endpoint is https://api.boomtax.com/mcp, using Streamable HTTP and OAuth. API access must be enabled on your BoomTax account; contact support@boomtax.com if needed.

Release status (October 9, 2026): the hosted API update is deployed, and the remote server is published in the official MCP Registry as io.github.boomtax/mcp-server, version 2.0.0. The npm 2.0.0 client is not yet published; npm 1.0.0 uses legacy password authentication. Use the remote connection or run the local client from this source tree. See release validation for client verification and remaining publication work.

Tools

These tools cannot create, edit, delete, or submit filings. The local client forwards these ten tools to the hosted service and blocks other tool names. Use list_filing_types for current form availability, rather than a static list that can go stale each tax year.

Setup

Remote connection (recommended)

Use https://api.boomtax.com/mcp in a client that supports Streamable HTTP and OAuth with PKCE. Complete the browser sign-in when prompted. OAuth client registration uses Dynamic Client Registration (DCR); choose automatic registration if your client offers a choice between DCR and a published client identity. Client ID Metadata Documents (CIMD) are not currently supported.

Discovery endpoints:

• https://api.boomtax.com/.well-known/oauth-protected-resource
• https://api.boomtax.com/.well-known/oauth-authorization-server

A 401 response when opening /mcp without authentication is expected. It includes a WWW-Authenticate discovery header. A bare URL in a browser is not an authenticated connection test.

Local client (version 2)

Requires Node.js 22 or newer. Create a read-scoped API credential at BoomTax API credentials. Supply the values through your client's secret storage or environment:

The client obtains short-lived OAuth tokens and authenticates again when a token expires. It does not use an account email/password. HTTP is allowed only for loopback development servers; other origins require HTTPS.

Run the source version after setting those environment variables:

git clone https://github.com/boomtax/mcp-server.git
cd mcp-server
npm ci
node index.js

After the 2.0.0 release is published, the equivalent package command is:

npx -y @boomtax/mcp-server@2.0.0

On Windows, clients that cannot spawn npx directly can use cmd /c npx -y @boomtax/mcp-server@2.0.0, or invoke the installed client with node and an absolute path to index.js.

Configuration by AI client

Claude Desktop and Claude web

For a remote connection, open Connectors, add a custom connector, and enter https://api.boomtax.com/mcp. Choose automatic OAuth client registration and complete sign-in. Organization accounts may require an administrator to add the connector first. Remote connectors are configured through the connector UI, not a URL-only entry in claude_desktop_config.json.

For a local source install in Claude Desktop, use an absolute path and inject the two credential environment variables securely:

{
  "mcpServers": {
    "boomtax": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/index.js"],
      "env": {
        "BOOMTAX_CLIENT_ID": "YOUR_READ_SCOPED_CLIENT_ID",
        "BOOMTAX_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Keep files containing secrets outside source control. Windows paths in JSON need doubled backslashes or forward slashes.

Claude Code

claude mcp add boomtax --transport http https://api.boomtax.com/mcp

Use /mcp in Claude Code to complete authentication.

ChatGPT

In a workspace that permits custom MCP connections, add a custom connector or plugin with URL https://api.boomtax.com/mcp, choose OAuth and automatic client registration, then complete sign-in. The exact UI and availability depend on your workspace controls. If asked for a pre-registered OAuth client instead, contact BoomTax support; a machine-to-machine API credential is not an authorization-code client registration.

Codex

codex mcp add boomtax --url https://api.boomtax.com/mcp
codex mcp login boomtax

Codex uses the hosted server's OAuth discovery metadata. A local stdio client can also run node with the source path above and inherit BOOMTAX_CLIENT_ID and BOOMTAX_CLIENT_SECRET from its environment.

Cursor and Windsurf

Add this remote server to your client's MCP configuration, then complete OAuth sign-in:

{
  "mcpServers": {
    "boomtax": {
      "url": "https://api.boomtax.com/mcp"
    }
  }
}

Cursor uses .cursor/mcp.json. In Windsurf or Devin Desktop, use the MCP settings' Open MCP config file action to select the configuration for your installed version. If a client version does not support OAuth for remote servers, use the local source configuration instead.

VS Code / GitHub Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "boomtax": {
      "type": "http",
      "url": "https://api.boomtax.com/mcp"
    }
  }
}

Start the server from VS Code's MCP controls and complete OAuth sign-in. This configuration contains no account secrets.

Example prompts

• "What filings do I have for tax year 2025?"
• "Summarize my filings by status."
• "What is the e-file status of this filing?"
• "Show errors on my 1099-NEC filing."
• "Which filing types and tax years are available?"

Security and troubleshooting

• Data access is scoped to the authenticated account and its filing permissions.
• Structured payer TIN fields are masked by the hosted service. Results still contain confidential names, contact details, and filing information; share them only with authorized assistants.
• Use a separate read-scoped API credential per local integration, and revoke it in BoomTax when no longer needed.
• Credentials are kept in memory by the local client. It pins OAuth discovery to the configured API issuer and does not log upstream error bodies or credentials.
• A local startup failure usually means missing client credentials, disabled API access, or an unreachable API. Do not supply BOOMTAX_API_USERNAME / BOOMTAX_API_PASSWORD; these version 1 settings are obsolete.
• An invalid_redirect_uri registration error requires a supported callback host or a support-assisted registration. Never work around it by sending credentials to another host.
• Directory health checks need an authorized test connection. A missing test profile can produce an unhealthy badge even when OAuth discovery is reachable.

Development

npm ci
npm test
npm run check
npm pack --dry-run

Tests use a loopback OAuth/MCP fixture and synthetic data, including a real stdio client process. They do not connect to customer accounts. See release and directory maintenance for publication prerequisites and verification.

License

The local client source in this repository is MIT licensed. Access to the hosted BoomTax service remains subject to BoomTax's service terms and account permissions.