toconline-mcp
Optional integration for archiving invoice PDFs from email via Gmail.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@toconline-mcp list my recent invoices"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
TOCOnline MCP
Unofficial. This is an independent, community-built project. It is not affiliated with, endorsed by, or supported by TOCOnline or Cloudware S.A. "TOCOnline" is a trademark of its respective owner. Use at your own risk — see the warranty disclaimer.
Local MCP server wrapping the TOCOnline accounting/invoicing API. Lets AI assistants list customers, look up products, draft sales documents, and call arbitrary TOCOnline endpoints on your behalf — after a one-time OAuth login.
Quick start
The whole setup is four steps. Each links to its full section below.
Install the launcher (needs Python 3.11+ and
uv):git clone https://github.com/themiguelamador/toconline-mcp.git cd toconline-mcp && uv tool install --from . toconline-mcp→ puts a
toconline-mcplauncher on yourPATH. Details.Get your TOCOnline API credentials — in the TOCOnline web app, Empresa → Configurações → Dados API, request access and set the redirect URL to
http://127.0.0.1:53682/callback. You'll end up with five values (client_id,client_secret, two OAuth URLs, an API URL). Details.Register the server with your client — one line for Claude Code, a small JSON block for Claude Desktop. Details.
Log in — ask your assistant "Log in to TOCOnline" (paste the five values), or run
toconline-mcp setup. A browser opens, you approve, done. Details.
That's it — read-only use works on any plan. Creating/editing documents needs an active GC license. Gmail is a separate, optional add-on for archiving invoice PDFs from email — skip it unless you want it (details).
Related MCP server: QuickBooks Online MCP Server
Status
Alpha. Covers the most common read and write operations for customers, suppliers,
products, and commercial sales documents, plus a generic api_request escape
hatch.
Prerequisites
macOS or Linux (Windows untested).
Python 3.11+.
A TOCOnline account with admin access and, for anything beyond
GETrequests, an active GC (Gestão Comercial) license.GET-only use works on any plan.An API integration configured in TOCOnline — see Getting TOCOnline API credentials below.
uv(recommended) orpipxor plainpython3 -m venv.
Install
Not yet published to PyPI — install from source:
git clone https://github.com/themiguelamador/toconline-mcp.git
cd toconline-mcp
# Recommended: uv
uv tool install --from . toconline-mcp
# → installs to ~/.local/share/uv/tools/toconline-mcp/
# → launcher at /Users/<you>/.local/bin/toconline-mcp
# Or pipx
pipx install .
# Or vanilla Python
python3 -m venv ~/.local/toconline-mcp
~/.local/toconline-mcp/bin/pip install .macOS sandbox note. Claude Desktop is sandboxed and cannot execute binaries whose Python installation lives under
~/Documents/,~/Desktop/, or~/Downloads/. The server will fail to start withPermissionError: … /.venv/pyvenv.cfg. Always install via one of the methods above — they all land outside the TCC-protected folders. Do not point Claude Desktop at a.venv/bin/toconline-mcpthat lives inside your cloned repo if the repo sits in~/Documents/.
Updating after code changes
When you pull new commits or edit the source, three steps — and which you need depends on what changed:
# 1. Rebuild the installed launcher (always)
uv tool install --from . toconline-mcp --reinstallRestart the server — fully quit the client (Claude Desktop: ⌘Q, not just the window) and reopen, or kill the running
toconline-mcpprocess so it respawns with the new code.Start a new chat — only needed when you added or renamed a tool. The chat caches the tool list it got at startup, so a new tool won't appear in an existing conversation even after the server restarts.
Editing an existing tool's behaviour needs only steps 1–2; adding or renaming a tool needs all three. See Iteration workflow for the full explanation and how to find/kill stale processes.
Getting TOCOnline API credentials
Based on the official TOCOnline API docs. These steps are one-time per company/tenant.
1. Request API access
In the TOCOnline web app, go to Empresa → Configurações → Dados API (Company → Settings → API Data). Fill in the integrator details (company info + contact email) and submit.
TOCOnline will email the integrator address a temporary link (valid ~72h) where you can view and edit the API credentials and integration settings.
2. Read the values off the email link page
The link page shows five values you will need:
TOCOnline variable | What it is | Use in this MCP |
| OAuth client id |
|
| OAuth client secret |
|
| Your tenant's OAuth base URL |
|
| Your tenant's API base URL |
|
| Callback URL (pre-set by TOCOnline; editable) | must match what this MCP uses — see next step |
The
OAUTH_URL/API_URLvalues are tenant-specific. Use the exact values shown on the email link page — the defaultapi_basebaked into this tool (https://apiv1.toconline.com) is a generic placeholder and may not match your tenant.
3. Set the redirect URL to match this MCP
This is the single step most people get wrong. TOCOnline pre-fills
OAUTH_REDIRECT_URL with something like http://127.0.0.1:4080/oauth/callback.
This MCP expects http://127.0.0.1:53682/callback (different port,
different path).
On the email link page (or later, back in Empresa → Configurações → Dados API),
overwrite OAUTH_REDIRECT_URL with exactly:
http://127.0.0.1:53682/callbackSave. That's it.
If port 53682 is taken on your machine, pick any free port and pass it as
redirect_port to the login tool (or --port N to the CLI). The path
must remain /callback.
4. Log in
Two equivalent ways — pick whichever fits your workflow.
A. From inside your AI client (recommended)
After registering the server with Claude, ask:
Log in to TOCOnline. Here are the values from Empresa → Configurações → Dados API: client_id =
..., client_secret =..., auth_url =<OAUTH_URL>/auth, token_url =<OAUTH_URL>/token, api_base =<API_URL>.
Claude invokes the login tool, your browser opens to TOCOnline consent,
you approve, and credentials land in
~/.config/toconline-mcp/credentials.json (mode 0600). No separate
terminal step.
Any time later, ask Claude to run auth_status to see whether credentials
are configured and how long until the access token expires, or logout
to clear them.
B. From the command line
toconline-mcp setupPrompts for each value interactively, opens the browser, writes the credentials file. You can also set them in the environment first to skip the prompts:
export TOCONLINE_CLIENT_ID='...'
export TOCONLINE_CLIENT_SECRET='...'
export TOCONLINE_AUTH_URL='<OAUTH_URL>/auth'
export TOCONLINE_TOKEN_URL='<OAUTH_URL>/token'
export TOCONLINE_API_BASE='<API_URL>'
toconline-mcp setupIf the MCP server is already running in your client, restart/reconnect it afterwards — it caches credentials in memory at startup, so
auth_statuswill show the fresh token while real calls still fail withunauthorized_clientuntil the server reloads the file.
Token lifetime
Per TOCOnline's auth docs,
the access token lasts 4 hours (expires_in: 14400) and the refresh
token 8 hours. This MCP refreshes the access token automatically (2 minutes
before expiry) whenever you make a request, so during active use you never
notice.
The catch is the 8-hour refresh window: if the server sits idle for more
than 8 hours, the refresh token expires and the next call fails with a
401 — you'll need to re-run login / setup. (This is a TOCOnline limit, not
something this MCP can extend.) You also re-login if you revoke the
integration, rotate the client secret, or change OAUTH_REDIRECT_URL.
Register with Claude
Both clients need the absolute path to the installed launcher. Find yours with:
which toconline-mcp
# → e.g. /Users/<you>/.local/bin/toconline-mcpClaude Code
claude mcp add toconline -- /Users/<you>/.local/bin/toconline-mcpClaude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json and
add the toconline entry under mcpServers:
{
"mcpServers": {
"toconline": {
"command": "/Users/<you>/.local/bin/toconline-mcp"
}
}
}Fully quit Claude Desktop (⌘Q — closing the window is not enough) and
reopen it. toconline should now appear in your connectors list with a
DESKTOP badge.
If the server doesn't show up
Check the log:
tail -50 ~/Library/Logs/Claude/mcp-server-toconline.logTwo common errors:
PermissionError: … /.venv/pyvenv.cfg— sandbox blocked the venv. Install viauv tool install --from . toconline-mcp(see above) and point the config at~/.local/bin/toconline-mcp, not a.venvunder~/Documents/.ENOENT/ command not found — the path in the config is wrong. Runwhich toconline-mcpagain and paste that exact path into the config.
Once this package is published to PyPI
After a uv publish, the config can use the shorter portable form that doesn't
depend on a specific user's filesystem:
{
"mcpServers": {
"toconline": { "command": "uvx", "args": ["toconline-mcp"] }
}
}API coverage
Targets the TOCOnline Open API v1.0.0 (JSON:API), documented at
api-docs.toconline.pt with the full
OpenAPI 3.0.3 spec on SwaggerHub
(68 paths). The base URL is
region-specific — e.g. https://api14.toconline.pt (the digits match your
account's region). A few document actions (finalize, email) use TOCOnline's
legacy v1 action endpoints, which aren't in the public docs but ship in the
Postman collection from Empresa → Configurações → Dados API.
Mapped against the public docs — ✅ typed tool, ⚠️ partial, ❌ api_request only:
API section (docs) | Resource | Coverage |
Empresa | Clientes (+ morada, e-mail) | ✅ full CRUD + addresses/contacts |
Empresa | Fornecedores (+ morada, e-mail) | ✅ full CRUD + addresses/contacts |
Empresa | Produtos e Serviços | ✅ full CRUD |
Vendas | Documentos de Venda | ✅ list/get/create/delete |
Vendas | Recibos de Venda | ✅ list/get/create + void |
Vendas | PDF (documento + recibo) | ✅ |
Vendas | Envio por e-mail | ✅ |
Vendas | Comunicação à AT | ✅ |
Compras | Documentos de Compra | ✅ list/get/create + finalize/void |
Compras | Pagamentos | ✅ list/get/create |
Compras | PDF / Comunicação à AT | ✅ pdf url + |
Auxiliares | Descritores de Taxa | ✅ |
Auxiliares | Família de Itens | ✅ |
Auxiliares | Países | ✅ |
Auxiliares | Unidades de Medida | ✅ |
Auxiliares | Contas Bancárias | ✅ |
Auxiliares | Caixa Associada | ✅ |
Auxiliares | Unidade Monetária (moedas) | ❌ |
Auxiliares | Taxas (tax rates) | ❌ |
Auxiliares | Categorias de Despesa | ❌ |
Auxiliares | Documentos de Série | ❌ |
Auxiliares | OSS (países e taxas) | ❌ |
Vendas/Compras | Settlement / payment lines | ✅ |
Anything ❌ works today through api_request with no new code — the four
uncovered auxiliary tables are read-only lookups. Ask if you want any promoted
to a typed tool.
Validation status
How far each recently added/changed tool has been verified — live = a real call against the API succeeded; unit = payload shape covered by tests but not run against the API; untested = no automated or live check yet.
Tool(s) | Status |
| ✅ live |
| ✅ live |
| ✅ live |
| ✅ live |
| 🧪 unit |
| 🧪 unit |
| 🧪 unit |
| 🧪 unit — money path, not run live (settles real documents) |
| ⏳ untested — binding AT submission |
Tools
54 typed tools plus a generic escape hatch. The typed tools expose exact-match
filters only, but the underlying API
supports comparison operators
— e.g. filter="documents.pending_total>0" or
document_lines.created_at>'2022-01-01'::date. Reach for api_request with a
raw filter param when you need ranges or date comparisons.
Authentication
Tool | Purpose |
| Check whether credentials are configured and when the access token expires. |
| Run the OAuth browser flow and store credentials. |
| Delete stored credentials. |
Customers, suppliers, products
Tool | Purpose |
| Customer CRUD. |
| Supplier CRUD. |
| Product CRUD. |
| Service CRUD. |
delete_* require confirm=true. Create/update set the API-required item
type attribute (Product/Service) automatically.
Reference tables (read-only)
Lookup resources used when building documents and items.
Tool | Purpose |
| ISO country codes and names. |
| Item families for categorizing products/services ( |
| Units (unidades) for document lines. |
| VAT rates and their codes ( |
| Cash accounts (caixas) for receipts/payments. |
| Document series (séries) per type — |
Addresses & contacts
Addresses and contacts are separate JSON:API resources with an owning
customer_id or supplier_id (exactly one, not both).
Tool | Purpose |
| Address CRUD. Scope listings by |
| Contact CRUD with the same scoping. |
delete_address / delete_contact require confirm=true.
Sales documents & receipts
Tool | Purpose |
| Filter by |
| Single document, with its line items merged by default. |
| Draft document with line items. For credit/debit notes, set |
| Customer-payment receipts. |
| Settle a sales document against a receipt (settlement line). |
Purchases
Tool | Purpose |
| Supplier invoices. |
| Supplier payments. |
| Settle a purchase document line against a payment (settlement line). |
Escape hatch
Tool | Purpose |
| Generic |
Listing a parent's children: some collections can't be filtered flat —
GET /api/commercial_sales_document_lines?filter[document_id]=…and/api/addresses?filter[customer_id]=…both returnJA011. Use the nested route instead:/api/commercial_sales_documents/{id}/lines,/api/customers/{id}/addresses. The typed tools already do this.
Response shape
Responses are flattened from JSON:API — data.attributes.* fields are hoisted
to the top level, and relationships.<name>.data.id becomes <name>_id:
{
"items": [
{"id": "1", "type": "customers", "business_name": "ACME", "country_code": "PT"}
],
"meta": {"total": 1}
}Document actions (PDF, email, finalize, void, AT)
Tool | Purpose |
| Get a signed public URL to the PDF of a sales document, sales receipt, or purchase document. The URL works unauthenticated for a short time — share it with a user and they can download. |
| Email a sales document or receipt to a recipient via TOCOnline's mail servers. |
| Issue a draft document. Irreversible — requires |
| Void (anular) a document. Irreversible — requires |
| Report a finalized document to the AT (tax authority). Binding — requires |
These endpoints aren't in the public API docs but are discoverable via the Postman collection TOCOnline provides from Empresa → Configurações → Dados API.
Settlement linking
create_sales_receipt_line / create_purchase_payment_line attach a receipt or
payment to the document it settles (so the document is marked paid). The two are
asymmetric, per the API:
Sales settle a whole document:
receivable_type="Document",receivable_id= the sales document id.Purchases settle a document line:
payable_type="Purchases::DocumentLine",payable_id= a purchase document line id (not the document id).
The tools build the documented payload; the settlement amounts (received_value
/ paid_value, settlement_amount, retention_total, …) are the caller's
responsibility.
The four uncovered auxiliary read tables (currencies, taxes, expense categories,
document series, OSS) stay on api_request — ask and we'll promote any to a
typed tool.
Gmail integration (optional)
Most people don't need this. It's a separate add-on for one workflow: pulling supplier-invoice PDFs out of email and archiving them into a folder (local or Google-Drive/iCloud-synced), so you can then enter them in TOCOnline. It's invoice-archiving only — not a general Gmail client (no send, no delete). Completely independent of the TOCOnline tools.
Off by default — nothing to do if you don't want it. The 10
gmail_*tools only appear once Gmail credentials exist (or you setTOCONLINE_GMAIL=1). If you do want it, the three steps are below:
One-time Google Cloud setup — create an OAuth client (you bring your own Google credentials).
Log in once via the CLI —
toconline-mcp gmail-setup.Restart your client — the
gmail_*tools now show up.
One-time Google Cloud setup
Go to https://console.cloud.google.com/ and create (or pick) a project.
APIs & Services → Library → enable Gmail API.
APIs & Services → OAuth consent screen → set up a "Desktop"/"External" consent screen with your email as a test user.
APIs & Services → Credentials → Create Credentials → OAuth client ID → Desktop app (or Web app). Register
http://127.0.0.1:53683/callbackas an Authorized redirect URI.Copy the Client ID and Client secret.
Log in
First login must use the CLI (the in-Claude gmail_* tools don't exist until
credentials are present):
toconline-mcp gmail-setupTokens are saved to ~/.config/toconline-mcp/gmail-credentials.json (0600),
separate from the TOCOnline credentials. Restart your client afterwards — the
gmail_* tools (including gmail_login for re-auth) now appear.
Scope
gmail.modify — covers reading messages, downloading attachments, and
adding/removing labels. It does not allow permanent deletion or sending
messages. Narrower scopes (like gmail.readonly or gmail.labels) can't
label messages, which breaks the "mark as imported" workflow.
Gmail tools (10)
Tool | Purpose |
| Auth lifecycle (mirrors TOCOnline's auth trio). |
| Search with Gmail query syntax ( |
| Fetch a single message's metadata + attachment list. |
| Download one attachment to an absolute local path. Handles filename collisions with |
| Discover and create labels. |
| Mark messages as processed (e.g. apply an |
Example workflow: bulk-download supplier invoices
Ask Claude:
Search my Gmail for unread messages from
billing@senders with PDF attachments since 2026-04-01. For each one, download every PDF to/Users/me/Google Drive/Invoices/2026-04/and apply the labelImported/TOCOnline. Then print a summary table.
Claude uses: gmail_search_messages → gmail_list_labels (or gmail_create_label
if missing) → for each result gmail_download_attachment + gmail_add_label_to_message.
Using a Google-Drive-synced folder for save_dir gives you cloud sync for free.
Gmail env vars
TOCONLINE_GMAIL_CREDENTIALS_PATH— override the credentials file location.GMAIL_CLIENT_ID/GMAIL_CLIENT_SECRET— skip the CLI prompts duringgmail-setup.
Config file (~/.config/toconline-mcp/.env)
Rather than exporting env vars in your shell every time, drop them in a
.env file and the MCP loads it at startup. Values from real environment
variables always win — the file is a fallback.
Loader checks these paths in order (first existing one wins):
Whatever
TOCONLINE_ENV_FILEpoints at (if set).~/.config/toconline-mcp/.env— primary location (next tocredentials.json)../.envin the current working directory (dev convenience).
Example file — all fields optional, include only what you want cached:
# ~/.config/toconline-mcp/.env
# --- TOCOnline ---
TOCONLINE_CLIENT_ID=ptNNNNNNNNN_cNNNNNN-xxxxxxxxxxxxxxxx
TOCONLINE_CLIENT_SECRET=your-rotated-secret
TOCONLINE_AUTH_URL=https://app14.toconline.pt/oauth/auth
TOCONLINE_TOKEN_URL=https://app14.toconline.pt/oauth/token
TOCONLINE_API_BASE=https://api14.toconline.pt
# --- Gmail (Google OAuth client from console.cloud.google.com) ---
GMAIL_CLIENT_ID=1234...apps.googleusercontent.com
GMAIL_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxxFormat:
KEY=VALUEper line.#comments and blank lines are fine.Quote values with spaces:
NAME="with spaces".export KEY=VALUEis accepted (for shell-compatibility).No variable interpolation (
$VAR/${VAR}) — export from shell if you need that.
After creating the file, toconline-mcp setup and toconline-mcp gmail-setup
skip the interactive prompts for any field the file already provides.
Permissions: the file contains OAuth client secrets, which are less sensitive than access tokens but still not public. Chmod it:
chmod 600 ~/.config/toconline-mcp/.envThe MCP prints a warning: on stderr if it detects looser permissions.
Development
uv venv --python 3.11
uv pip install -e '.[dev]'
pytestEnvironment variables:
TOCONLINE_CREDENTIALS_PATH— override the credentials file location.TOCONLINE_LOG_LEVEL—DEBUG,INFO,WARNING, etc. Logs go to stderr.
Iteration workflow (picking up code changes)
uv tool install --reinstall updates the binary on disk, but does not
restart already-running MCP processes — Python imports modules at startup,
so a live server keeps serving the old code until killed. After editing the
source:
# 1. Run the test suite (catches regressions before they hit the live server)
pytest
# 2. Refresh the installed launcher
uv tool install --from . toconline-mcp --reinstall
# 3. Find Claude Desktop's MCP server process and kill it
ps aux | grep toconline-mcp | grep -v grep
kill <pid>
# 4. Start a new chat in Claude Desktop (Cmd-N). The first tool call
# in that new chat causes Claude Desktop to respawn the MCP with the
# new code — and the new chat's LLM is given the fresh tool list.Why "new chat" matters even more than "kill the server"
There are two layers that cache things:
The MCP server process caches the registered tool list in memory (modules are imported at startup). Killing the process forces a respawn that re-imports the latest code.
The chat session caches the tool list it got from the server at chat start, baked into the LLM's context. Newly-added tools don't appear in an existing chat even after the server respawns.
So if you've added a tool (list_services for example) and you want the
LLM to be able to call it, you need both:
The kill+respawn (so the server exposes the new tool at all), AND
A new chat (so the LLM is told the new tool exists).
Editing an existing tool's behaviour or fixing a bug is different — the tool's name is the same, the LLM already knows about it, so just kill+respawn is enough; the next call hits the new code. Adding or renaming tools requires a new chat.
The same applies to Claude Code: the deferred tools list shown at session
start is locked in for that chat. New tools require a new Claude Code session
(/clear or starting fresh).
Stale processes
Stray uvx toconline-mcp processes from old terminals can linger and serve
stale code. ps aux | grep toconline-mcp shows them; kill <pid> clears
them. They're harmless when idle but confusing if you claude mcp add more
than one server pointing at the same binary.
Security
Tokens and client secrets stored in
~/.config/toconline-mcp/credentials.json(0600). The server refuses to start if permissions are looser.All logging is to stderr (stdout is reserved for MCP stdio framing). Authorization headers and token fields are redacted from log messages.
api_requestpath is constrained to^/api/...with no..; write methods require an explicitconfirm=true.
License
MIT.
Available Tools
67 toolsapi_requestA
Escape hatch for endpoints not covered by typed tools.
Path must match /api/<resource>[/<sub>...]. Destructive methods require
confirm=true. Prefer the typed tools (list_customers, create_sales_document,
etc.) when they fit.
Inputs: path (required), method (required), body, query, +2 more.
auth_statusA
Report whether TOCOnline credentials are configured and their expiry.
Fast, no side effects. Call this to decide whether to prompt the user
through login before attempting other tools.
Inputs: no named parameters. Returns: object
communicate_purchase_document_atA
Communicate a finalized purchase document to the AT (Portuguese tax authority).
Inputs: id (required), confirm. Returns: object
communicate_sales_document_atA
Communicate a finalized sales document to the AT (Portuguese tax authority).
Triggers TOCOnline's send_document_at_webservice action. The document
must already be finalized. Requires confirm=true because the report is
a binding fiscal submission. The response carries the AT communication
status/code returned by the webservice.
Inputs: id (required), confirm. Returns: object
create_addressA
Create an address attached to a customer or supplier.
TOCOnline uses a polymorphic association — the parent is identified
via the addressable_type ("Customer" | "Supplier") and
addressable_id attributes, not a JSON:API relationship.
Returns the created (or, on a duplicate, the existing) address re-fetched by id, so the parent link and all fields are populated — the raw POST echo omits them, which makes the address look empty/unlinked.
TOCOnline enforces a uniqueness constraint on address_detail + postcode
per parent and raises [400] já existe na tabela on a duplicate; this
tool catches that and returns the existing address (idempotent).
Inputs: city (required), address_detail (required), region, postcode, +3 more. Returns: object
create_contactC
Create a contact attached to a customer or supplier.
Polymorphic association via contactable_type ("Customer" | "Supplier")
and contactable_id attributes.
Inputs: name (required), email, position, categories, +5 more. Returns: object
create_customerB
Create a customer. Returns the created record.
Inputs: business_name (required), email, website, cashed_vat, +10 more. Returns: object
create_productB
Create a product. Returns the created record.
Inputs: item_code (required), item_description (required), tax_code, sales_price, +2 more. Returns: object
create_purchase_documentA
Create a purchase document with lines in a single v1 call.
Supplier identity fields (tax number, business name) are denormalized from the supplier record.
Inputs: date (required), lines (required), supplier_id (required), document_type (required), +4 more. Returns: object
create_purchase_paymentA
Create a purchase payment record.
Note: this creates the payment itself. To settle specific purchase
document lines against it, add create_purchase_payment_line calls
referencing this payment's id.
Inputs: date (required), gross_total (required), supplier_id (required), observations, +2 more. Returns: object
create_purchase_payment_lineA
Settle a purchase document line against a payment (settlement line).
Links an existing payment to a payable so the document line is marked
paid. Note the payable is a document line (payable_id), unlike sales
receipts which settle whole documents. Field values are the caller's
responsibility — this tool only builds the documented payload.
Inputs: paid_value (required), payable_id (required), payment_id (required), net_total, +6 more. Returns: object
create_sales_documentA
Create a sales document with line items.
Two code paths depending on finalize:
finalize=True— uses the v1 endpoint (POST /api/v1/commercial_sales_documents), which takes a flat body, embeds lines inline, and issues the document immediately (fiscally binding, irreversible). Customer identity fields are denormalized by fetching/api/customers/{customer_id}first.finalize=False(default) — uses the legacy JSON:API endpoint multi-step: POST the header to/api/commercial_sales_documents, then POST each line to/api/commercial_sales_document_lineswithdocument_idlinking. The document stays as a draft (status 0) — editable, not yet fiscally valid. To issue later, callfinalize_sales_document(id).
v1 ignores finalize=0 (the documented field), so the legacy path is
the only way to actually leave a doc in draft state via this API.
Customer identity (name, tax number, address) is denormalized onto the
header by TOCOnline server-side, on both paths — but only from the
customer's main address. If the header comes back with an empty
customer_address_detail, the customer has no main_address_id set;
fix the customer's address rather than passing address fields here.
Date: on a certified series the date cannot precede the series' last issued document. The API enforces this; we don't pre-check it (a type can have multiple series, so a client-side guess would risk blocking valid emissions).
Inputs: date (required), lines (required), customer_id (required), document_type (required), +6 more. Returns: object
create_sales_receiptA
Create a sales receipt (customer payment) record.
Note: this creates the receipt itself. To settle specific sales
documents against it, add create_sales_receipt_line calls referencing
this receipt's id.
Inputs: date (required), customer_id (required), gross_total (required), observations, +2 more. Returns: object
create_sales_receipt_lineB
Settle a sales document against a receipt (settlement line).
Links an existing receipt to a receivable so the document is marked paid. Field values (how much settles what) are the caller's responsibility — this tool only builds the documented payload.
Inputs: receipt_id (required), receivable_id (required), received_value (required), net_total, +6 more. Returns: object
create_serviceB
Create a service. Returns the created record.
Inputs: item_code (required), item_description (required), tax_code, sales_price, +2 more. Returns: object
create_supplierA
Create a supplier. Returns the created record.
Contacts (email/phone) and addresses are separate resources — use
create_contact / create_address with this supplier's id afterwards.
Inputs: business_name (required), tax_registration_number (required), website, is_taxable, +9 more. Returns: object
delete_addressA
Delete an address. Requires confirm=true.
Inputs: id (required), confirm. Returns: object
delete_contactA
Delete a contact. Requires confirm=true.
Inputs: id (required), confirm. Returns: object
delete_customerA
Delete a customer. Requires confirm=true.
Inputs: id (required), confirm. Returns: object
delete_productA
Delete a product. Requires confirm=true.
Inputs: id (required), confirm. Returns: object
delete_sales_documentA
Delete a draft sales document.
Use this for cleaning up unfinalised drafts (e.g. orphans left behind
by a failed create_sales_document call, or experimental drafts you
no longer want). Will fail if the document has been finalised
(status != 0) — finalised documents must be voided via a credit note,
not deleted.
Inputs: id (required), confirm. Returns: object
delete_serviceA
Delete a service. Requires confirm=true.
Inputs: id (required), confirm. Returns: object
delete_supplierA
Delete a supplier. Requires confirm=true.
Inputs: id (required), confirm. Returns: object
finalize_purchase_documentB
Finalize a draft purchase document.
Inputs: id (required), confirm. Returns: object
finalize_sales_documentA
Finalize (issue) a draft sales document.
Once finalized, the document becomes fiscally valid and immutable.
Requires confirm=true because the operation cannot be reversed.
Inputs: id (required), confirm. Returns: object
get_addressA
Fetch a single address by id.
Inputs: id (required). Returns: object
get_bank_accountA
Fetch a single bank account by id, enriched with derived id_banco
and pais_conta fields (see list_bank_accounts for the rules).
Inputs: id (required). Returns: object
get_bank_transactionB
Fetch a single bank transaction by id.
Inputs: id (required). Returns: object
get_contactA
Fetch a single contact by id.
Inputs: id (required). Returns: object
get_current_companyA
Return the authenticated company's own profile.
Includes tax_registration_number (NIPC for Portuguese companies),
business_name, tax_country_region, contact fields, currency_id,
accountant_tax_registration_number, and the linked address_id.
Use this when you need the reporting entity's own identity — for example when producing tax-authority reports (Modelo 30, SAFT-PT), where you need the company's NIPC as the reporter, not the customer's.
Inputs: no named parameters. Returns: object
get_customerA
Fetch a single customer by id.
Inputs: id (required). Returns: object
get_document_pdf_urlA
Get a signed, shareable URL to a PDF render of a document or receipt.
Returns a short-lived URL on app14.toconline.pt (or equivalent for
your tenant) that serves the rendered PDF. The URL is signed and does
not require authentication to open — give it to a user and they can
download the PDF in their browser. It typically expires after a few
hours.
Only finalized documents have a PDF. A draft (status 0) returns a "not ready for print" error — finalize it first.
Inputs: id (required), document_kind. Returns: object
get_productA
Fetch a single product by id.
Inputs: id (required). Returns: object
get_purchase_documentA
Fetch a purchase document, optionally with its line items merged.
Inputs: id (required), include_lines. Returns: object
get_purchase_paymentA
Fetch a single purchase payment by id.
Inputs: id (required). Returns: object
get_sales_documentC
Fetch a sales document, optionally with its line items merged.
Inputs: id (required), include_lines. Returns: object
get_sales_receiptA
Fetch a single sales receipt by id.
Inputs: id (required). Returns: object
get_serviceB
Fetch a single service by id.
Inputs: id (required). Returns: object
get_supplierB
Fetch a single supplier by id.
Inputs: id (required). Returns: object
list_addressesA
List addresses. Normally scope to a customer_id or supplier_id.
Scoping uses the nested route (/api/customers/{id}/addresses); the
flat /api/addresses?filter[customer_id]= query raises JA011.
Inputs: sort, fields, page_size, customer_id, +2 more. Returns: object
list_bank_accountsA
List company bank accounts (name, IBAN, SWIFT, type).
Each item is enriched with two derived fields:
pais_conta— ISO country code, fromiban[:2](e.g.PT,GB).id_banco— bank identifier:PTaccounts: first 4 digits ofnib(e.g.0007Novo Banco,0035Caixa Geral de Depósitos) — matches AT Tabelas_apoio.Foreign accounts:
swiftwhen present, elseiban[4:8].
Both are None when the underlying iban/nib/swift is empty — a
TOCOnline data-completeness issue to fix in the web UI or via PATCH.
These derived fields are what Portuguese reports like Modelo 30 (foreign payments declaration) and IES bank annexes ask for.
Inputs: sort, fields, page_size, page_number. Returns: object
list_bank_transactionsA
List bank transactions (movements) imported into TOCOnline.
All filters are exact match. To get a date range, make one call per
day or page through without a date filter. value is signed
(negative for debits, positive for credits).
Inputs: sort, fields, page_size, page_number, +3 more. Returns: object
list_cash_accountsB
List cash accounts (caixas) used for receipts/payments.
Inputs: sort, fields, page_size, page_number. Returns: object
list_contactsB
List contacts. Normally scope to a customer_id or supplier_id.
Inputs: sort, fields, page_size, customer_id, +2 more. Returns: object
list_countriesB
List countries (ISO codes, names).
Inputs: sort, fields, page_size, page_number. Returns: object
list_customersA
List customers. All filters are exact match.
Inputs: sort, email, fields, page_size, +3 more. Returns: object
list_item_familiesA
List item families — used to categorize products/services (item_family_id).
Inputs: sort, fields, page_size, page_number. Returns: object
list_productsC
List products. All filters are exact match.
Inputs: sort, fields, item_code, page_size, +2 more. Returns: object
list_purchase_documentsB
List commercial purchase documents, newest first by default.
Inputs: date, sort, fields, page_size, +3 more. Returns: object
list_purchase_paymentsC
List purchase payments, newest first by default.
Inputs: date, sort, fields, page_size, +2 more. Returns: object
list_sales_documentsA
List commercial sales documents, newest first by default.
Use page_number + page_size to paginate, and fields to limit
the response to just the columns you need.
Inputs: date, sort, fields, page_size, +3 more. Returns: object
list_sales_receiptsB
List sales receipts (customer payments), newest first by default.
Inputs: date, sort, fields, page_size, +2 more. Returns: object
list_servicesA
List services. All filters are exact match.
Services live at /api/services, separate from /api/products. Sales/
purchase document lines distinguish them via item_type (Service
vs Product).
Inputs: sort, fields, item_code, page_size, +2 more. Returns: object
list_suppliersB
List suppliers. All filters are exact match.
Inputs: sort, fields, page_size, page_number, +2 more. Returns: object
list_tax_descriptorsA
List tax descriptors — VAT rates and their codes (NOR, INT, RED, ISE).
Inputs: sort, fields, page_size, page_number. Returns: object
list_units_of_measureB
List units of measure (unidades) for document lines.
Inputs: sort, fields, page_size, page_number. Returns: object
loginA
Open a browser and complete OAuth login against TOCOnline.
The user must have registered http://127.0.0.1:<redirect_port>/callback
as a redirect URI in their TOCOnline integration. Credentials are stored
at ~/.config/toconline-mcp/credentials.json (mode 0600) and picked up
by subsequent tool calls without restarting the server.
This tool blocks for up to 3 minutes while waiting for the browser callback; ask the user to complete the consent promptly.
Inputs: auth_url (required), client_id (required), token_url (required), client_secret (required), +3 more. Returns: object
logoutA
Delete the stored TOCOnline credentials and drop in-memory tokens.
Inputs: no named parameters. Returns: object
send_document_emailA
Send a sales document or receipt to a recipient by email.
Uses TOCOnline's built-in email delivery — the message arrives from TOCOnline's mail servers with your document attached / linked.
Inputs: id (required), subject (required), to_email (required), from_name (required), +2 more. Returns: object
update_addressA
Update an address. Only non-null fields are sent.
Inputs: id (required), city, region, postcode, +2 more. Returns: object
update_contactA
Update a contact. Only non-null fields are sent.
Inputs: id (required), name, email, position, +3 more. Returns: object
update_customerA
Update a customer. Only non-null fields are sent.
Inputs: id (required), email, website, cashed_vat, +11 more. Returns: object
update_productA
Update a product. Only non-null fields are sent.
Inputs: id (required), tax_code, item_code, sales_price, +3 more. Returns: object
update_serviceB
Update a service. Only non-null fields are sent.
Inputs: id (required), tax_code, item_code, sales_price, +3 more. Returns: object
update_supplierA
Update a supplier. Only non-null fields are sent.
Inputs: id (required), website, is_taxable, self_billing, +10 more. Returns: object
void_purchase_documentC
Void (anular) a purchase document.
Inputs: id (required), confirm. Returns: object
void_sales_receiptC
Void (anular) a sales receipt.
Inputs: id (required), confirm. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 67 tools
Each resource type has distinct list/get/create/update/delete tools, and sales/purchase/receipt/payment tools are clearly separated by domain noun. A small amount of potential confusion exists between receipt creation and receipt settlement lines, and between `api_request` and typed tools, but the descriptions resolve this.
The dominant `verb_noun` pattern is consistent across CRUD resources (list_customers, get_customer, create_customer, update_customer, delete_customer). Deviations like `auth_status`, `login`, `logout`, and `api_request` break the otherwise regular style, but they are few and recognizable.
67 tools is a very large surface for a single MCP server and falls in the extreme-count range; an agent will struggle to choose among so many endpoints. Splitting by domain (customers, documents, banking, references) would make the toolset far more navigable.
The toolset covers full CRUD for core master data and a coherent document lifecycle: create draft, finalize, communicate to AT, void, PDF, and email. Notable gaps include no update for draft documents and no dedicated credit-note endpoint, but `api_request` provides an escape hatch.
Maintenance
Related MCP Connectors
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for Codat — companies, connections, invoices, bills and financial statements.
MCP server for MOCO business software: time tracking, projects, budgets, and invoicing via API
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server for Invoice Ninja v5 API. Enables AI assistants to manage clients, invoices, quotes, payments, and time tracking through natural language.3220 npm2MIT
- AlicenseNot gradedqualityDmaintenanceA local MCP server that exposes QuickBooks Online data and actions as callable tools for AI assistants.MIT
- AlicenseNot gradedqualityDmaintenanceA local MCP server that wraps the DocuGenerate API to generate documents (invoices, contracts, letters) from templates via natural language commands.MIT

makeleaps-mcpofficial
AlicenseAqualityDmaintenanceUnofficial MCP server to operate MakeLeaps clients, quotes, and invoices from LLMs via the MakeLeaps API, with local execution and no telemetry.8MIT