Content
# 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](#license).
Local [MCP](https://modelcontextprotocol.io) server wrapping the [TOCOnline](https://toconline.pt)
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.
1. **Install the launcher** (needs Python 3.11+ and [`uv`](https://github.com/astral-sh/uv)):
```bash
git clone https://github.com/themiguelamador/toconline-mcp.git
cd toconline-mcp && uv tool install --from . toconline-mcp
```
→ puts a `toconline-mcp` launcher on your `PATH`. [Details](#install).
2. **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](#getting-toconline-api-credentials).
3. **Register the server with your client** — one line for Claude Code, a small
JSON block for Claude Desktop. [Details](#register-with-claude).
4. **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](#4-log-in).
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](#gmail-integration-optional)).
## 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 `GET`
requests, 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](#getting-toconline-api-credentials) below.
- [`uv`](https://github.com/astral-sh/uv) (recommended) or `pipx` or plain `python3 -m venv`.
## Install
Not yet published to PyPI — install from source:
```bash
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 with
> `PermissionError: … /.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-mcp` that 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:
```bash
# 1. Rebuild the installed launcher (always)
uv tool install --from . toconline-mcp --reinstall
```
2. **Restart the server** — fully quit the client (Claude Desktop: ⌘Q, not
just the window) and reopen, or kill the running `toconline-mcp` process so
it respawns with the new code.
3. **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](#iteration-workflow-picking-up-code-changes) for the full
explanation and how to find/kill stale processes.
## Getting TOCOnline API credentials
Based on the [official TOCOnline API docs](https://api-docs.toconline.pt/).
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 id | `client_id` |
| `OAUTH_CLIENT_SECRET` | OAuth client secret | `client_secret` |
| `OAUTH_URL` | Your tenant's OAuth base URL | `auth_url` = `<OAUTH_URL>/auth`, `token_url` = `<OAUTH_URL>/token` |
| `API_URL` | Your tenant's API base URL | `api_base` |
| `OAUTH_REDIRECT_URL` | Callback URL (pre-set by TOCOnline; editable) | must match what this MCP uses — see next step |
> The `OAUTH_URL` / `API_URL` values are **tenant-specific**. Use the exact
> values shown on the email link page — the default `api_base` baked 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/callback
```
Save. 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](#register-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
```bash
toconline-mcp setup
```
Prompts for each value interactively, opens the browser, writes the
credentials file. You can also set them in the environment first to skip
the prompts:
```bash
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 setup
```
> If the MCP server is already running in your client, restart/reconnect it
> afterwards — it caches credentials in memory at startup, so `auth_status`
> will show the fresh token while real calls still fail with
> `unauthorized_client` until the server reloads the file.
### Token lifetime
Per TOCOnline's [auth docs](https://api-docs.toconline.pt/autenticacao-detalhada),
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:
```bash
which toconline-mcp
# → e.g. /Users/<you>/.local/bin/toconline-mcp
```
### Claude Code
```bash
claude mcp add toconline -- /Users/<you>/.local/bin/toconline-mcp
```
### Claude Desktop
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` and
add the `toconline` entry under `mcpServers`:
```json
{
"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:
```bash
tail -50 ~/Library/Logs/Claude/mcp-server-toconline.log
```
Two common errors:
- `PermissionError: … /.venv/pyvenv.cfg` — sandbox blocked the venv. Install
via `uv tool install --from . toconline-mcp` (see above) and point the
config at `~/.local/bin/toconline-mcp`, not a `.venv` under `~/Documents/`.
- `ENOENT` / command not found — the path in the config is wrong. Run
`which toconline-mcp` again 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:
```json
{
"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](https://api-docs.toconline.pt/) with the full
[OpenAPI 3.0.3 spec on SwaggerHub](https://app.swaggerhub.com/apis-docs/toconline.pt/toc-online_open_api/1.0.0)
(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) | ✅ `get_document_pdf_url` |
| Vendas | Envio por e-mail | ✅ `send_document_email` |
| Vendas | Comunicação à AT | ✅ `communicate_sales_document_at` |
| Compras | Documentos de Compra | ✅ list/get/create + finalize/void |
| Compras | Pagamentos | ✅ list/get/create |
| Compras | PDF / Comunicação à AT | ✅ pdf url + `communicate_purchase_document_at` |
| Auxiliares | Descritores de Taxa | ✅ `list_tax_descriptors` |
| Auxiliares | Família de Itens | ✅ `list_item_families` |
| Auxiliares | Países | ✅ `list_countries` |
| Auxiliares | Unidades de Medida | ✅ `list_units_of_measure` |
| Auxiliares | Contas Bancárias | ✅ `list_bank_accounts` / `get` |
| Auxiliares | Caixa Associada | ✅ `list_cash_accounts` |
| Auxiliares | Unidade Monetária (moedas) | ❌ `api_request` |
| Auxiliares | Taxas (tax rates) | ❌ `api_request` |
| Auxiliares | Categorias de Despesa | ❌ `api_request` |
| Auxiliares | Documentos de Série | ❌ `api_request` |
| Auxiliares | OSS (países e taxas) | ❌ `api_request` |
| Vendas/Compras | Settlement / payment lines | ✅ `create_sales_receipt_line` / `create_purchase_payment_line` |
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 |
|---|---|
| `list_countries`, `list_item_families`, `list_units_of_measure`, `list_tax_descriptors`, `list_cash_accounts` | ✅ live |
| `create_product` (incl. required `type` + `item_family_id`) | ✅ live |
| `delete_product` | ✅ live |
| `create_service`, `delete_service` | ✅ live |
| `update_product`, `update_service` | 🧪 unit |
| `create_customer` / `update_customer` / `delete_customer` | 🧪 unit |
| `create_supplier` / `update_supplier` / `delete_supplier` | 🧪 unit |
| `create_sales_receipt_line`, `create_purchase_payment_line` | 🧪 unit — money path, not run live (settles real documents) |
| `communicate_sales_document_at`, `communicate_purchase_document_at` | ⏳ 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](https://api-docs.toconline.pt/caracteristicas-dos-pedidos)
— 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 |
|---|---|
| `auth_status` | Check whether credentials are configured and when the access token expires. |
| `login` | Run the OAuth browser flow and store credentials. |
| `logout` | Delete stored credentials. |
### Customers, suppliers, products
| Tool | Purpose |
|---|---|
| `list_customers` / `get_customer` / `create_customer` / `update_customer` / `delete_customer` | Customer CRUD. |
| `list_suppliers` / `get_supplier` / `create_supplier` / `update_supplier` / `delete_supplier` | Supplier CRUD. |
| `list_products` / `get_product` / `create_product` / `update_product` / `delete_product` | Product CRUD. |
| `list_services` / `get_service` / `create_service` / `update_service` / `delete_service` | 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 |
|---|---|
| `list_countries` | ISO country codes and names. |
| `list_item_families` | Item families for categorizing products/services (`item_family_id`). |
| `list_units_of_measure` | Units (unidades) for document lines. |
| `list_tax_descriptors` | VAT rates and their codes (`NOR`, `INT`, `RED`, `ISE`). |
| `list_cash_accounts` | Cash accounts (caixas) for receipts/payments. |
| `list_document_series` | Document series (séries) per type — `prefix`, numbering, `is_default`. Pass a series id as `series_id` to `create_sales_document`. |
### Addresses & contacts
Addresses and contacts are separate JSON:API resources with an owning
`customer_id` or `supplier_id` (exactly one, not both).
| Tool | Purpose |
|---|---|
| `list_addresses` / `get_address` / `create_address` / `update_address` / `delete_address` | Address CRUD. Scope listings by `customer_id` or `supplier_id`. |
| `list_contacts` / `get_contact` / `create_contact` / `update_contact` / `delete_contact` | Contact CRUD with the same scoping. |
`delete_address` / `delete_contact` require `confirm=true`.
### Sales documents & receipts
| Tool | Purpose |
|---|---|
| `list_sales_documents` | Filter by `document_type` / `customer_id` / `date`. |
| `get_sales_document` | Single document, with its line items merged by default. |
| `create_sales_document` | Draft document with line items. For credit/debit notes, set `document_type='NC'` or `'ND'` and pass `parent_document_id` to reference the original. |
| `list_sales_receipts` / `get_sales_receipt` / `create_sales_receipt` | Customer-payment receipts. |
| `create_sales_receipt_line` | Settle a sales document against a receipt (settlement line). |
### Purchases
| Tool | Purpose |
|---|---|
| `list_purchase_documents` / `get_purchase_document` / `create_purchase_document` | Supplier invoices. |
| `list_purchase_payments` / `get_purchase_payment` / `create_purchase_payment` | Supplier payments. |
| `create_purchase_payment_line` | Settle a purchase document line against a payment (settlement line). |
### Escape hatch
| Tool | Purpose |
|---|---|
| `api_request` | Generic `/api/*` passthrough for endpoints without typed tools. `POST`/`PATCH`/`PUT`/`DELETE` require `confirm=true`. |
> **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 return `JA011`. 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`:
```json
{
"items": [
{"id": "1", "type": "customers", "business_name": "ACME", "country_code": "PT"}
],
"meta": {"total": 1}
}
```
### Document actions (PDF, email, finalize, void, AT)
| Tool | Purpose |
|---|---|
| `get_document_pdf_url` | 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. |
| `send_document_email` | Email a sales document or receipt to a recipient via TOCOnline's mail servers. |
| `finalize_sales_document` / `finalize_purchase_document` | Issue a draft document. Irreversible — requires `confirm=true`. |
| `void_sales_receipt` / `void_purchase_document` | Void (anular) a document. Irreversible — requires `confirm=true`. |
| `communicate_sales_document_at` / `communicate_purchase_document_at` | Report a finalized document to the AT (tax authority). Binding — requires `confirm=true`. |
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 set `TOCONLINE_GMAIL=1`).
> If you do want it, the three steps are below:
>
> 1. **One-time Google Cloud setup** — create an OAuth client (you bring your
> own Google credentials).
> 2. **Log in once via the CLI** — `toconline-mcp gmail-setup`.
> 3. **Restart your client** — the `gmail_*` tools now show up.
### One-time Google Cloud setup
1. Go to <https://console.cloud.google.com/> and create (or pick) a project.
2. **APIs & Services → Library** → enable **Gmail API**.
3. **APIs & Services → OAuth consent screen** → set up a "Desktop"/"External"
consent screen with your email as a test user.
4. **APIs & Services → Credentials → Create Credentials → OAuth client ID**
→ *Desktop app* (or *Web app*). Register
`http://127.0.0.1:53683/callback` as an Authorized redirect URI.
5. 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):
```bash
toconline-mcp gmail-setup
```
Tokens 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 |
|---|---|
| `gmail_auth_status` / `gmail_login` / `gmail_logout` | Auth lifecycle (mirrors TOCOnline's auth trio). |
| `gmail_search_messages` | Search with Gmail query syntax (`has:attachment filename:pdf from:billing@…`). Returns compact metadata + attachment list per message. |
| `gmail_get_message` | Fetch a single message's metadata + attachment list. |
| `gmail_download_attachment` | Download one attachment to an absolute local path. Handles filename collisions with ` (2)`, ` (3)`… suffixes. |
| `gmail_list_labels` / `gmail_create_label` | Discover and create labels. |
| `gmail_add_label_to_message` / `gmail_remove_label_from_message` | Mark messages as processed (e.g. apply an `Imported/TOCOnline` label). |
### 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 label
> `Imported/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 during
`gmail-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):
1. Whatever `TOCONLINE_ENV_FILE` points at (if set).
2. `~/.config/toconline-mcp/.env` — primary location (next to `credentials.json`).
3. `./.env` in the current working directory (dev convenience).
Example file — all fields optional, include only what you want cached:
```bash
# ~/.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-xxxxxxxxxxxxxxxxxxxx
```
Format:
- `KEY=VALUE` per line.
- `#` comments and blank lines are fine.
- Quote values with spaces: `NAME="with spaces"`.
- `export KEY=VALUE` is 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:
```bash
chmod 600 ~/.config/toconline-mcp/.env
```
The MCP prints a `warning:` on stderr if it detects looser permissions.
## Development
```bash
uv venv --python 3.11
uv pip install -e '.[dev]'
pytest
```
Environment 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:
```bash
# 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:
1. **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.
2. **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_request` path is constrained to `^/api/...` with no `..`; write methods
require an explicit `confirm=true`.
## License
MIT.
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available