Developer documentation

Plug an AI assistant into your MADATA workspace

Every <workspace>.madata.app workspace ships an MCP server: an AI assistant, or your own code, reads and writes your business data with your permissions.

Your workspace's MCP server exposes ~150 business tools (KPIs, sales, accounting, payroll, journal entries…) to an external client: Claude, ChatGPT, Gemini, Mistral Le Chat, or a program you write. Every call runs with the permissions of the user who owns the key.

01Quick start in 3 steps

Create an API key. In MADATA, open My profile → Account security → API keys and generate a key. It starts with mia_ and is shown only once. Restricted to workspace MADATA administrators. Details.
Get the workspace URL. It looks like https://<workspace>.madata.app/mia/mcp and appears next to the key.
Call it. A JSON-RPC POST with the Authorization: Bearer header:

bashlist available tools

curl -s https://<workspace>.madata.app/mia/mcp \
  -H "Authorization: Bearer mia_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

To connect Claude or Mistral Le Chat, there is no key to paste: they connect over OAuth with the URL alone. See Connect an assistant.

02What the MCP server can do

On a fresh workspace, 150 tools are exposed (73 read, 77 write). The list actually visible depends on the installed modules, the user's permissions and the key's scope.

Family	Examples
KPIs	`get_kpi`, `get_cash_flow`, `get_crm_kpi`, `get_revenue_forecast`
Business reads	`search_sales`, `search_invoices`, `get_stock_card`, `query_records`
Accounting	`get_balance_sheet`, `check_accounting_consistency`, `export_accounting`, `create_journal_entry`
Writes	`create_quotation`, `create_customer_invoice`, `register_payment`, `action_record`
HR & payroll	`create_payslip`, `validate_batch`, `send_payslip`, `create_leave`
Communication	`send_email`, `prepare_whatsapp_message`, `send_payment_followups`

The server also exposes 4 resources (mia://kpi/current…) and 8 prompts ready to use. Full list: Tool catalog.

03Conventions

Endpoint: https://<workspace>.madata.app/mia/mcp: one per workspace.
Auth: Authorization: Bearer mia_… header, or OAuth 2.1 (Claude, Mistral).
Language: Error messages and tool descriptions are in French.
Name: The platform is called MADATA.

Security

A key never elevates permissions: every call runs as the real user, with their native rights. Billed resources (users, companies, points of sale, apps) stay read-only: manage them in the portal.

04Support

Something missing, a tool misbehaving? From a connected assistant, ask it to log a request: the suggest_feature_request tool submits it. Otherwise, use support from your client area.