How it works

The Taxually MCP server lets an AI assistant call Taxually's APIs on your behalf over the Model Context Protocol. You authorize it once with a Taxually API key; the assistant itself never receives that key.

Connecting

1. Add the MCP server URL (from the home page) to your AI client.
2. The client opens an authorization window served by this site.
3. You paste a Taxually API key and choose Production or Test.
4. We validate the key against Taxually, encrypt it, and store it server-side. Your client receives only a short-lived access token.

What the assistant can do

Scoped to whatever your API key can see. In chat it should first ask whether you want to type a company ID or select from your companies, then:

• List companies on your key.
• Fetch return and data periods for a company.
• Summarize sales & purchases (VAT / net amounts, transaction counts) by period, country, or tax code.

Managing your connections

There is no account to sign into — your API key is the identity. Because of that, pasting the key on the home page under Your connections is enough to prove ownership and:

• See where the key is active — Test and Production are tracked as separate connections — with when each was last used.
• Disconnect any connection, which deletes its stored copy from this server. It does not change the key in Taxually.

Switching keys or environments

Each connection is bound to one key and one environment, so switching which key or environment your assistant uses means re-authorizing:

1. (Optional) Disconnect the current one under Your connections.
2. Force a fresh authorization in your client so the authorize window re-opens:
   • Claude / ChatGPT connectors: disconnect and re-add the connector.
   • Cursor / Claude Desktop (mcp-remote): clear the cached credential (rm -rf ~/.mcp-auth), then reconnect.
3. In the authorize window, paste the key and pick the environment you want.

You don't need to switch to move between test and prod — you can connect both at once and each client holds one at a time.

Security

• The API key is encrypted at rest and used only server-side to call Taxually — the assistant never sees it.
• The connection uses standard OAuth 2.1 with PKCE. Access tokens are short-lived (about an hour) and refresh automatically; if a stored key is removed or a token expires, your client re-authorizes.
• To fully cut access, disconnect under Your connections and rotate the key in Taxually.

The API key is the identity for data access. Treat it like a password: only paste it into the Taxually authorization window.