# 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](mailto: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](docs/release.md) for client verification and remaining publication work. ## Tools | Tool | Description | |---|---| | `list_filings` | Filter filings by year, form type, and status; includes filing system | | `get_filing_details` | Filing details, payer summary, and e-file status | | `get_filing_summary` | Counts by status and form type | | `list_filing_forms` | Paginated form metadata within a filing | | `get_form` | Form metadata, status, and dates | | `get_efile_status` | E-file request and response timeline | | `get_efile_errors` | E-file errors and messages | | `list_payers` | Payers across accessible filings | | `get_payer` | Payer details, including a masked payer TIN | | `list_filing_types` | Available filing types, tax years, and filing systems | 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](https://boomtax.com/Account/Api/Create). Supply the values through your client's secret storage or environment: | Variable | Required | Purpose | |---|---|---| | `BOOMTAX_CLIENT_ID` | Yes | API credential client ID | | `BOOMTAX_CLIENT_SECRET` | Yes | API credential secret | | `BOOMTAX_API_URL` | No | Defaults to `https://api.boomtax.com`; specify an origin, not `/mcp` | 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: ```sh 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: ```sh 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: ```json { "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 ```sh 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 ```sh 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: ```json { "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`: ```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 ```sh 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](docs/release.md) for publication prerequisites and verification. ## License The local client source in this repository is [MIT licensed](LICENSE). Access to the hosted BoomTax service remains subject to BoomTax's service terms and account permissions.