Integrate Soluta over MCP
Soluta is a remote MCP server for the accounting books of businesses in Vietnam (Circulars 133 and 99). Soluta accepts connections from Claude, ChatGPT and Grok/Cursor (OAuth sign-in). Other channels are not open yet. This page only describes what is running today.
Endpoint
| Item | Value |
|---|---|
| MCP | https://mcp.soluta.vn/mcp |
| Transport | Streamable HTTP |
| Protocol | use 2025-06-18; the server also accepts 2024-11-05, 2025-03-26, 2025-11-25, 2026-07-28 |
| Protected resource | https://mcp.soluta.vn/.well-known/oauth-protected-resource/mcp |
| Authorization server | https://auth.mcp.soluta.vn · metadata /.well-known/oauth-authorization-server |
Quick start
Claude, ChatGPT and Grok/Cursor: follow the connection guide. Other channels are not open yet.
Authentication (OAuth 2.1)
- Calling
/mcpwithout a token ⇒401withWWW-Authenticate: Bearer resource_metadata="…/oauth-protected-resource/mcp", scope="soluta.so". - Read the resource metadata ⇒ authorization server
https://auth.mcp.soluta.vn⇒ read/.well-known/oauth-authorization-server. - Client registration: Client ID Metadata Document (
client_idis an https URL) or DCR (POST /register). Public clients:token_endpoint_auth_method = none. - Authorization code + PKCE S256 (required). Scope
soluta.so. - https redirects match the registration exactly.
- The user signs in to soluta.vn (email or Google), chooses a company, then clicks Allow. The consent screen shows your redirect domain.
- Access tokens carry
aud = https://mcp.soluta.vn/mcpand are bound to exactly one book the user chose (claimsoluta_so). For another book, add another connection. - Refresh tokens rotate: each exchange returns a new refresh token and retires the old one; reusing an old one revokes the whole chain. Expired / revoked ⇒
invalid_grant.
Writing and approval
- Tools only draft proposals (
soluta_proposal_create…). The books do not change until the user approves. - Approval happens in the Soluta card (MCP Apps
ui://) right in the conversation: the user checks the entry, legal basis and documents, then clicks Approve. - Soluta currently accepts connections only from Claude and ChatGPT; other channels are not open yet.
Document files
- The server does not accept file bytes. Sending a
content_base64argument ⇒ error resultKHONG_NHAN_TEP. - Read invoices / bank statements / balance sheets on the client, then send the fields:
soluta_einvoice_import⇒invoices,soluta_opening_draft⇒balances.
Tools
The list can change between releases — always read tools/list. This is the tools/list your client sees (server 0.9.1263).
| Name | Title | Kind |
|---|---|---|
soluta_books_open | Open accounting books | Has side effects |
soluta_proposal_list | List proposals | Read-only |
soluta_proposal_show | Show proposal | Read-only |
soluta_proposal_create | Propose journal entry | Has side effects |
soluta_balance | Account balance | Read-only |
soluta_accounts | Chart of accounts | Read-only |
soluta_parties | Parties | Read-only |
soluta_trial_balance | Trial balance | Read-only |
soluta_balance_sheet | Balance sheet (B01) | Read-only |
soluta_income_statement | Income statement (B02) | Read-only |
soluta_reconcile_bank | Reconcile bank statement | Read-only |
soluta_party_propose | Propose party | Has side effects |
soluta_company_propose | Propose company profile | Has side effects |
soluta_vat_return | VAT return (01/GTGT) | Read-only |
soluta_period_close_propose | Propose period close | Has side effects |
soluta_company | Company profile | Read-only |
soluta_einvoice_import | Read e-invoice XML | Read-only |
soluta_worksheet_create | Build worksheet | Read-only |
soluta_proposal_approve_in_chat | Post to ledger | Writes the books · destructiveHint |
soluta_proposal_approve_from_ui | Post from review card | Writes the books · destructiveHint |
soluta_proposal_reject_from_ui | Reject from review card | Writes the books · destructiveHint |
soluta_opening_draft | Draft opening balances | Read-only |
soluta_book_create | Create new book | Has side effects |
soluta_law_search | Search law | Read-only |
soluta_law_show | Show law article | Read-only |
soluta_law_gap | Report law gap | Has side effects |
soluta_feedback | Send feedback to Soluta | Has side effects |
soluta_precedents | Precedents | Read-only |
soluta_party_balances | Party balances | Read-only |
soluta_ledger | General ledger and journal | Read-only |
soluta_financial_report | Financial report | Read-only |
soluta_report_export | Export report file | Read-only |
soluta_review | Review book | Read-only |
soluta_manage | Management reports | Read-only |
soluta_tax | Tax returns and deadlines | Read-only |
soluta_trace | Trace entries and figures | Read-only |
soluta_correct | Propose correction | Has side effects |
soluta_fixed_asset | Draft depreciation | Has side effects |
soluta_prepaid | Draft prepaid allocation | Read-only |
soluta_period_close_draft | Draft closing entries | Read-only |
soluta_contractor_tax | Draft foreign contractor tax | Read-only |
soluta_payroll | Draft payroll | Read-only |
soluta_cit_return | Draft corporate income tax | Read-only |
Common errors
| You see | Meaning | What to do |
|---|---|---|
HTTP 401 + WWW-Authenticate | missing, invalid or expired token | run OAuth from resource_metadata; use the refresh token if expired |
HTTP 403 DUONG_LECH_SO_CUA_TOKEN | the token was issued for a different book than the one in /mcp/<book code> | use that book’s token, or call /mcp |
error result KHONG_NHAN_TEP | file bytes were sent | read the file on the client and send fields (see “Document files”) |
error result QUA_TAI | one call exceeds a computation limit | split it into smaller calls |
HTTP 429 | too many requests in a short time (rate limit) | wait and retry, slow down |
invalid_grant at /token | refresh token expired, used or revoked | ask the user to reconnect |
Contact
Integration questions and bug reports: info@soluta.vn.