FAQ & troubleshooting

The server doesn't show up in Claude Desktop / Cursor

Check your MCP config path and JSON, then fully restart the client. Verify the command runs standalone: npx -y mcp-portugal should start and print mcp-portugal ready (stdio) to stderr. Node 20+ is required.

How do I test it without a client?

Use the MCP Inspector: npx @modelcontextprotocol/inspector npx -y mcp-portugal, then call a tool such as list_holidays with { "year": 2026 }.

Are the holidays official / always correct?

They cover the national mandatory holidays, including movable (Easter-based) ones computed with the Anonymous Gregorian algorithm. Municipal holidays and the optional Carnival Tuesday are intentionally excluded, since they aren't national by law.

Does validate_nif confirm the NIF is real?

No — it validates structure and the check digit only, and classifies the taxpayer type. It doesn't call the AT.

Can it run fully offline?

Yes. All tools are deterministic and local — no network, no API keys.

Can I add my own tools?

Yes — put pure logic in src/lib/, register a tool in src/index.ts with a zod schema, and add a test. See CONTRIBUTING.