mcp-fiscal-brasil lists 44 tools but reads only three environment variables

Three ways to be a server sit in one dependency list

The manifest names three server frameworks, which is unusual and reflects the project's interface choices rather than duplication.

There is the higher-level framework for building MCP servers, the protocol SDK itself, and a web framework with its own server. Any one of those is enough to be an MCP server; all three are installed.

The news section explains why. Beyond the MCP server, the project ships a standalone command-line client, a REST API with a bundled demo web interface, and a Node wrapper that is still in preview and lives in its own directory.

The command-line surface is a separate binary from the server, with subcommands for a company lookup, a compliance check, and a regime comparison that takes revenue, sector, and payroll figures as flags.

mcp-fiscal cnpj 12345678000190
mcp-fiscal regimes --faturamento 500000 --setor serviços --folha 180000

So the same library is reachable four ways, and which one you use determines whether you get a tool server, a script, or a web app.

Exactly three environment variables are read by the code

The environment template is longer than it is useful, and it says so.

The header states that the server works completely with no variable defined, that every option below is optional, and that they only matter in HTTP or server-sent-events mode. In the default mode, used by desktop clients, none of them is needed.

Then it names the three that the code actually reads: the transport protocol, the TCP port, and the bind host. The rest of the file is commentary.

The transport variable accepts four spellings of two ideas, so a typo here is the failure to watch for: standard streams for local clients, and three names for a remote deployment.

The port is ignored in the default mode, and the host defaults to binding on every interface, which is the right default for a container and the wrong one for a laptop on public wifi.

The practical reading is that you can ignore the whole file unless you are deploying remotely, and even then only the transport variable is usually worth changing.

The A1 certificate is the one variable that changes the HTTP contract

One feature needs credentials, and the documentation is unusually careful about them.

An A1 digital certificate is required to query the real status service of a state tax authority, and for electronic invoice manifestation and distribution over the REST interface. Without it the service keeps working, and everything else behaves normally.

The exception is one endpoint. The status call returns HTTP 503 with a message that the certificate is not configured, because the underlying call requires mutual TLS. So the failure is explicit and scoped, which is better than a silently wrong answer about whether an invoice was authorized.

The handling warning is the part to follow. The certificate password must never be written in plaintext into a version-controlled environment file or a shared environment, and in production it should be configured as a secret mounted as a file or injected as a variable, rather than passed as an environment variable that a container inspection command or a provider console will display.

That is a specific operational instruction, and it is the difference between a credential that leaks into logs and one that does not.

The container healthcheck guesses which mode it is in

The image runs an MCP server over standard streams by default, which opens no port, and the health check has to cope with that.

The script behind the health check detects whether a port is actually listening. If it is, the check calls the health endpoint over HTTP. If it is not, the check falls back to confirming only that the package imports. The same image therefore serves both modes with one check.

The compose file takes the simpler path for the REST service, testing the health endpoint directly on a thirty-second interval with a short timeout and three retries. That service also sets a rate limit and a cache lifetime that the HTTP-mode MCP service does not set, so the two are not configured identically even though they run the same image.

The second compose service, which runs the server over HTTP transport instead of standard streams, sits behind an optional profile, so it does not start with a plain compose up. You have to name it.

Both services restart unless stopped, and both build from the same local image rather than pulling one.

Six composed workflows sit on top of the 44 tools

The advertised surface is 44 tools. The comparison table against other Brazilian servers separately lists six higher-level agentic tools, and those six are the ones described as workflows.

They are named functions rather than a taxonomy. A supplier risk score returns a number from zero to a hundred with the risk level, the contributing factors, and a hiring recommendation. A batch lookup takes several company identifiers in one call and returns compliance plus a score per company. A compliance report combines the registry record, the Simples or MEI status, and the industry code into something actionable. A full invoice validation checks the XML, the access key, and the issuer, returning structured issues. A SPED summary gives an executive summary with the period, the company, the blocks, and inconsistencies. A regime comparison puts four tax regimes side by side.

That is the real product surface. The other 38 tools are the registry, invoice, and reference-table lookups these six are assembled from.

The distinction matters for an agent: the high-level tools return a recommendation rather than raw rows, which is what makes them usable in a prompt without post-processing.

The newest-features section is two majors behind the version

The readme's changelog section describes version 0.2, while the manifest declares 0.5.1.

That section is where the eight added data sources, the six agentic tools, the extra interfaces, and the production hardening items are described. All of that shipped, and the manifest confirms the current version, but the section heading was never updated.

The container file carries the same staleness. Its usage comments build and run the image with a 0.2.0 tag, while the wheel it actually installs is the one the manifest names.

The release history explains the gap: two releases on the same afternoon at the end of June, a patch and a minor, with the previous day carrying the release that added invoice support and a tax reform simulator.

None of this breaks anything, since the tags in comments and the heading in prose are both inert. It does mean a reader assessing maturity from the readme alone will date the project roughly a year earlier than the manifest does.

Four deployment targets and three registry listings

The file list shows how many audiences this project is addressing.

Deployment comes first: a multi-stage container definition, a compose file, a configuration file for one container platform, and another for a different one, plus the documented one-click route through a free web host whose demo can take about half a minute to wake on first access.

Distribution listings come next, with two files that publish the server to external MCP directories, and a separate manifest for automated releases, which explains the release tags appearing without a human choosing them.

Quality tooling is visible too: a vulnerability scanner configuration, a code review bot configuration, a pre-commit setup, and a lock file.

Documentation is a static site generator configuration beside a documentation directory, and the documentation is linked from the repository header rather than only from a hosted site.

The examples directory is the clearest statement of intended use. Eight scripts cover a first call, a registry lookup, invoice XML parsing, SPED validation, batch validation, and three integration paths: a web framework, a Django project, and an accounting system.

Editorial conclusion

mcp-fiscal-brasil suits a developer or accountant wiring fiscal data into an assistant or an internal system without registering for four different government portals, since the offline tables and parsers cover the parts that do not need authentication. It does not suit anyone expecting live SEFAZ status, because that single endpoint returns a 503 until an A1 certificate is mounted as a secret. Before you rely on it, pin the version past the runner cache, and treat the certificate password as a mounted file rather than an environment variable.

Frequently asked questions

Official sources

1. DeHor-Labs/mcp-fiscal-brasil on GitHub
2. License: MIT
3. Project website
4. README
5. Releases