Taxually MCP Back

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 — the environment (Production or Test) follows the server URL you connected with.
  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

Four read-only tools, scoped to whatever your API key can see. Nothing here changes your Taxually data. Every tool except ping works on one company at a time, and get_companies is where that ID comes from — so in chat the assistant should first ask whether you want to type a company ID or pick from your companies.

Inputs in blue are required; the rest are optional.

get_companies Lists the companies your key can act on.

Each one comes back with its name, ID and country. This is the definitive list — a company missing from it can't be reached with that key.

  • companyName
  • maxResults
get_return_periods The tax returns produced for a company.

Jurisdiction, return type, status, VAT amount, currency and filing deadlines, newest first. Filter by date range, or by status to see only the returns waiting for approval.

  • companyId
  • dateFrom
  • dateTo
  • status
get_data_periods The months of transaction data, and how each one processed.

Ask for a single month to get its per-file transaction, error and warning counts, and the reason if it failed.

  • companyId
  • period
ping Checks the connection is alive.

Answers “pong” and touches no data. Takes no inputs.

Your client may also offer a prompt called taxually_select_company. It just walks through the same choice — type an ID, or pick from the list — before any data is fetched.

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.