Conta Simples MCP
Enable AI agents to perform real operations on the Conta Simples platform
Overview
The Conta Simples MCP server enables AI agents to interact directly with the Conta Simples platform. It exposes a curated set of tools that allow agents to query financial data, manage cards, and automate operational workflows — all through natural language conversations.
This MCP server performs real operations on your Conta Simples account. Actions taken by AI agents through this server are subject to your user permissions, rate limits, and audit requirements.
What you can do
The Conta Simples MCP enables AI-powered workflows across key financial operations:
Monthly closing & control - "Which expenses are missing receipts this
month?" - "Are there any transactions outside our spending policy in the last 30 days?" - "Compare total spend by category this week vs last week"
Reconciliation & accounting - "Export all March expenses with invoices
for my ERP" - "Which transactions have not been categorized yet?" - "Group travel expenses this month by user"
Credit limit & cards - "What is my current available credit card limit?"
- "Show me all virtual cards and their status" - "Which team members have an active card?"
Expense proofs & receipts - "Which transactions are still missing
receipts?" - "Upload a receipt for this transaction" - "Show me the OCR data extracted from this expense proof"
Setup
Conta Simples MCP server URL:
https://mcp.contasimples.com/mcp
Authentication is OAuth 2.1 with PKCE, and compliant agents identify themselves, with no prior registration. Protocol details are in the Authentication & security section, starting at Discovery.
Prerequisites
Before connecting the Conta Simples MCP, you'll need:
- A Conta Simples account: an active user with access to the Internet Banking.
- An MCP-compatible agent: any agent that supports remote MCP over HTTP and runs the OAuth flow in the browser.
Step by step per agent
The step by step for each agent is in the Conector MCP article in the Help Center (Portuguese).
Other agents
The URL is the same for any MCP-compatible agent:
https://mcp.contasimples.com/mcp
- In your agent's MCP server settings screen, add a new server with this URL.
- If it asks for the connection type, choose HTTP or remote.
- On the first connection, the browser opens the Internet Banking login screen.
If your agent asks for a required Client ID, use the connector's public value. It is not a secret and it is the same for everyone.
72ic737n3eng9k1l3s02kbeplk
If it asks for a fixed callback port, you don't need one. Any port works.
If it only accepts an API key or token, connecting is not possible yet.
Connecting your account
The first time your client connects, the Conta Simples MCP walks you through OAuth in the browser:
Sign in to Conta Simples
A browser window opens to the Internet Banking login. Sign in with the same credentials you use every day.
Confirm with your security code
Open the Conta Simples mobile app, tap the menu on the top-left, and go to Segurança → Token de segurança. Enter the 6-digit code shown there to confirm the sign-in.
You're ready
Your authorization is stored securely and tokens are refreshed automatically — you won't need to sign in again unless you revoke access or your session expires.
Stuck during sign-in? The Help Center article is organized by symptom, and Support can help with anything it does not cover.
Available tools
The Conta Simples MCP exposes the following tools, organized by domain:
Transactions
| Tool | Description | Reads | Writes |
|---|---|---|---|
get-card-transactions___ | Paginated credit card transactions with optional ISO date range (max 62 days), limit (5–100), and rich filters including amount, card IDs, categories, reconciliation status, and attachments | ✅ | |
get-banking-transactions___ | Paginated banking (account) transactions with optional date range, sorting, and filters for types, amounts, categories, and reconciliation status | ✅ | |
get-banking-transaction-receipt___ | Returns a short-lived link (about 5 minutes) to the PDF receipt Conta Simples generates for a banking transaction: bill payment, outgoing Pix or TED, transfer between Conta Simples accounts, or secured card deposit. Requires transactionId, the numeric id returned by get-banking-transactions___ (not the originId); showReceipt: true marks the entry types that have a receipt. When there is none, it returns reason (TRANSACTION_NOT_FOUND, RECEIPT_NOT_AVAILABLE, RECEIPT_TYPE_NOT_SUPPORTED) and message instead of the link | ✅ | |
review-transactions___ | Marks one or more card or banking transactions as reviewed ("conferida") in the expense conference flow. Requires items with the originId and the transactionSource (CARD or BANKING) of each transaction. The batch is all-or-nothing and cannot be undone | ✅ |
Users
| Tool | Description | Reads | Writes |
|---|---|---|---|
get-users___ | Lists company users with optional filtering, field selection, and pagination | ✅ |
Cards & limits
| Tool | Description | Reads | Writes |
|---|---|---|---|
get-cards___ | Lists cards with optional filters for type (VIRTUAL/PHYSICAL), status, and email; returns items with pagination | ✅ | |
get-credit-card-limit___ | Returns the available credit card limit for the authenticated company | ✅ | |
block-card___ | Blocks a corporate payment card immediately. Requires cardId, a blockStatus (BLOCKED, BLOCKED_MAX_PURCHASE_QUANTITY, BLOCKED_TRANSACTIONS_DECLINED, BLOCKED_BY_BPO), and a free-text reason for auditing | ✅ | |
unblock-card___ | Unblocks (reactivates) a previously blocked corporate card. Requires cardId | ✅ |
Credit card bills
| Tool | Description | Reads | Writes |
|---|---|---|---|
get-bills___ | Lists all credit card bills for the company, sorted ascending by cut date, with optional status filter (CLOSED, OPEN, FUTURE, OVERDUE, EXPIRED) | ✅ | |
get-bill-details___ | Returns the details of a specific bill by dueDate (YYYY-MM-DD), including national/international totals, IOF, credits, charges, and individual transactions | ✅ |
Account
| Tool | Description | Reads | Writes |
|---|---|---|---|
get-account-balance___ | Returns the company's available account balance as a single numeric value in BRL. Not available to restricted roles (CARD_MANAGER, CARD_USER) | ✅ |
Cashback
| Tool | Description | Reads | Writes |
|---|---|---|---|
get-cashback-balance___ | Returns the company's cashback balance available for redemption, in BRL, plus the amount that expires in the next 30 days and its nearest expiration date. Read-only: redemption is not available through MCP, and it returns neither the amount already redeemed nor the cashback history | ✅ |
Categories
| Tool | Description | Reads | Writes |
|---|---|---|---|
get-categories___ | Lists all categories—both default and custom—with ID, name, type, and timestamps | ✅ | |
create-category___ | Creates a custom (MANUAL) expense category for the company. Requires name (min. 2 characters), unique per company. Not idempotent — list the existing categories first | ✅ | |
update-category___ | Renames an existing category. Requires the id returned by get-categories___ plus the new name. Names stay unique per company | ✅ | |
delete-category___ | Logically deletes a category in two steps: the first call with only id returns confirmationRequired: true, and a second call with confirmDelete: true performs the deletion. It cannot be undone | ✅ |
Suppliers
| Tool | Description | Reads | Writes |
|---|---|---|---|
get-suppliers___ | Lists the company's active suppliers one page at a time (page, pageSize, default 50), or searches them by names and returns every match at once. With exact: true (default) a name matches the whole name ignoring case; with exact: false it matches by substring | ✅ | |
get-supplier___ | Returns one supplier by id, taken from get-suppliers___. It also resolves an id from the legacy supplier system and returns the supplier with its current id | ✅ | |
create-supplier___ | Creates a manually registered (MANUAL) supplier. Requires name, unique per company ignoring case, and accepts optional cnpjs with or without formatting. If the name already exists, nothing is created: the existing supplier returns with alreadyExisted: true and the cnpjs sent are not applied | ✅ | |
update-supplier___ | Renames a supplier and/or replaces its CNPJ list. Requires id plus name, cnpjs or both. cnpjs replaces the whole list instead of appending to it, and an empty list is rejected | ✅ | |
delete-supplier___ | Logically deletes a supplier in two steps: the first call with only id returns confirmationRequired: true and the supplier record, and a second call with confirmDelete: true performs the deletion. It cannot be undone | ✅ |
Cost centers
| Tool | Description | Reads | Writes |
|---|---|---|---|
get-cost-centers___ | Lists the company's cost centers one page at a time (page, pageSize, default 50, max 100), or searches them by names and returns every match at once, with the same exact rule as get-suppliers___. The returned id feeds the costCenterIds filter of the transaction tools | ✅ | |
get-cost-center___ | Returns the name and origin of one cost center by costCenterId, taken from get-cost-centers___ or from the costCenterId returned by get-cards___ and the transaction tools | ✅ | |
create-cost-center___ | Creates a company-defined (MANUAL) cost center. Requires name, unique per company ignoring case; the Geral cost center already exists in every company. Not idempotent — check with get-cost-centers___ first | ✅ | |
update-cost-center___ | Renames a cost center. Requires costCenterId and the new name. Names stay unique per company | ✅ | |
delete-cost-center___ | Logically deletes a cost center in two steps: the first call with only costCenterId returns confirmationRequired: true, and a second call with confirmDelete: true performs the deletion. Links to cards, expenses and transactions are not checked, and it cannot be undone | ✅ |
Expense proofs
| Tool | Description | Reads | Writes |
|---|---|---|---|
create-expense-proof___ | Registers an expense proof and returns a presigned upload URL. It reserves the proof slot only; file upload happens separately to the URL, then asynchronous OCR/validation and auto-binding are performed. | ✅ | |
get-transaction-attachment___ | Retrieves the files the user attached to a transaction (invoices, receipts) and returns short-lived presigned URLs for download. If none exist, returns an empty list and a recommendation rather than an error. For the receipt Conta Simples generates for a banking transaction, use get-banking-transaction-receipt___ | ✅ | |
get-expense-proof___ | Fetches an expense proof by ID, including binding status, optional OCR data, linked transaction, and file URL | ✅ |
For create-expense-proof to work in Claude, the generated upload URL (https://file-upload.contasimples.com/) must be allowed in the Claude sandbox.
Upload the file with an HTTP PUT to the returned signedUrl within 1 hour, as a PDF, PNG or JPEG. Always send an explicit User-Agent header, for example Mozilla/5.0: requests with the default Python urllib User-Agent are blocked with HTTP 403 error code: 1010 (using requests instead of urllib also works). Keep the URL exactly as returned, including the x-amz-checksum-crc32 parameter, which is expected. A new URL cannot be issued for an existing proof: if the upload fails, create a new proof with create-expense-proof___.
Global Account
These tools only cover the Global Account — the company's international/multi-currency (USD) account provided by Airwallex. Use them only when the request explicitly mentions Global Account, an international account, USD or international transfers; generic balance, card and statement questions are answered by the BRL tools above.
| Tool | Description | Reads | Writes |
|---|---|---|---|
global-account-get-details___ | Returns the company's Global Account details, including the receiving bank account data used for incoming international payments | ✅ | |
global-account-get-onboarding-status___ | Consolidated onboarding and activation status of the Global Account, including pending KYC or RFI | ✅ | |
global-account-get-balance___ | Balances per currency held in the Global Account, each with available, pending, reserved and total amounts | ✅ | |
global-account-list-balance-history___ | Balance movement history — credits, debits, transfers and fees. Optional limit and offset | ✅ | |
global-account-list-future-transactions___ | Future or processing transactions, especially BRL to USD conversions that have not settled yet. Optional limit and offset | ✅ | |
global-account-list-cards___ | Lists the international (USD) cards visible to the authenticated user. Optional limit and offset | ✅ | |
global-account-get-card-details___ | Details of a single Global Account card by cardId: brand, masked number, status, label, cardholder and configured spending limits | ✅ | |
global-account-get-card-available-limits___ | Remaining available spending limits of a Global Account card. Requires cardId | ✅ | |
global-account-list-card-transactions___ | Card transactions of the Global Account. Managers may list the whole company; other users must pass a cardId visible to them. Optional startDate, endDate, limit, offset | ✅ | |
global-account-get-card-transaction-details___ | Details of a card transaction by transactionId, with the settled amount and the original amount/currency charged by the merchant | ✅ | |
global-account-check-transfer-in-availability___ | Whether the company can receive funds into the Global Account and which transfer-in methods are available | ✅ | |
global-account-get-transfer-limits___ | Transfer-in limits of the Global Account: per operation, daily and monthly. Optional provider | ✅ | |
global-account-get-transfer-in-details___ | Details of a specific transfer-in by transactionId. Optional provider | ✅ | |
global-account-get-transfer-in-conversion-details___ | FX details of a transfer-in conversion by provider conversion id: source and target amounts, quote rate, spread, fees and payer institution | ✅ |
Example workflows
The Conta Simples MCP supports a wide range of natural language queries across financial operations. Below are three featured workflow examples followed by a full capability map organized by domain.
Prompts marked as Coming soon depend on tools currently under development and will be available in a future release.
Monthly closing review
You: "Which expenses are still missing receipts this month?"
The agent will:
- Call
get-card-transactions___filtered to the current month - Filter results for transactions with no attached proof
- Group by user and rank by unreceipted amount
Expected response:
I found 12 transactions this month with no receipt attached, totaling R$4,870.00:
User Transactions Amount Ana Lima 4 R$2,100.00 Carlos Mendes 5 R$1,620.00 Tech Team 3 R$1,150.00 Would you like me to generate upload links for each of these transactions?
Cash flow & limit forecast
You: "What is the projected spend until end of month — will I exceed the account limit?"
The agent will:
- Call
get-credit-card-limit___to retrieve the current available limit - Call
get-card-transactions___for the current month's spend - Calculate the daily spending rate and project through end of month
Expected response:
Available card account limit: R$80,000.00 Spent so far this month: R$48,200.00 (60.3%)
At your current daily pace of R$2,230.00/day, projected spend by end of month is R$66,900.00 — leaving a buffer of R$13,100.00.
You are not at risk of exceeding the limit this month.
Expense proof upload
You: "I have an invoice here — attach it for me"
The agent will:
- Call
get-card-transactions___to identify the most relevant unreceipted transaction - Call
create-expense-proof___to generate a secure signed upload URL - Return the URL for file upload (PDF, PNG, or JPEG)
- Call
get-expense-proof___after upload to confirm the binding
Expected response:
I found a matching transaction: Restaurante Figueira Rubaiyat — R$340.00 on Mar 29.
A secure upload link has been created for your invoice (valid for 15 minutes):
https://upload.contasimples.com/receipts/signed/xyz789...Upload your PDF, PNG, or JPEG to the link above. The receipt will be automatically linked to the transaction once uploaded.
Capability map
Monthly closing & control
| Prompt | Tools | Status |
|---|---|---|
| "Which expenses are still missing receipts this month?" | get-card-transactions___ | ✅ |
| "What is the total spend by category this week vs. last week?" | get-card-transactions___ get-categories___ | ✅ |
| "What percentage of transactions have receipts vs. are missing receipts in March?" | get-card-transactions___ | ✅ |
| "Who are the users with the highest volume of unreceipted spending?" | get-card-transactions___ get-users___ | ✅ |
| "Are there any expenses outside the spending policy in the last 30 days?" | get-card-transactions___ + policy tools | ⏳ |
| "List all transactions violating an active control policy" | get-card-transactions___ + policy tools | ⏳ |
| "Are there transactions with suppliers not registered in the system?" | get-card-transactions___ + supplier tools | ⏳ |
Cash flow & credit
| Prompt | Tools | Status |
|---|---|---|
| "What is my available balance on the card account right now?" | get-cards___ get-credit-card-limit___ | ✅ |
| "What is the projected spend until end of month — will I exceed the account limit?" | get-card-transactions___ get-credit-card-limit___ | ✅ |
| "Do I have any recurring payment that increased in value?" | get-banking-transactions___ | ✅ |
| "How is the card account limit distributed across active cards?" | get-cards___ get-credit-card-limit___ | ✅ |
| "Which cash outflows recur every month on this date?" | get-banking-transactions___ | ✅ |
| "What is my available account balance right now?" | get-account-balance___ | ✅ |
| "Do I have any overdue credit card bills?" | get-bills___ | ✅ |
| "What is the credit card bill for June — show the transactions?" | get-bills___ get-bill-details___ | ✅ |
| "How much cashback can we redeem, and is any of it about to expire?" | get-cashback-balance___ | ✅ |
| "Is there any recurring supplier worth negotiating early payment?" | get-banking-transactions___ + supplier tools | ⏳ |
Card & team management
| Prompt | Tools | Status |
|---|---|---|
| "Who has a blocked card?" | get-cards___ | ✅ |
| "Which team members haven't used their card this month?" | get-users___ get-card-transactions___ | ✅ |
| "Are there cards with spending concentrated in a single category — possible misuse?" | get-cards___ get-card-transactions___ | ✅ |
| "What is the ranking of users by spending volume this quarter?" | get-users___ get-card-transactions___ | ✅ |
| "Is any card's limit close to the total card account limit?" | get-cards___ get-credit-card-limit___ | ✅ |
| "Create a virtual card for cost center X with limit Y" | card creation tool | ⏳ |
| "Block the card for user X" | get-cards___ block-card___ | ✅ |
| "Unblock the card for user X" | get-cards___ unblock-card___ | ✅ |
| "Block cards for all users who spent more than R$X this month" | get-card-transactions___ block-card___ | ✅ |
Expense proof flow
| Prompt | Tools | Status |
|---|---|---|
| "I have an invoice here — attach it for me" | create-expense-proof___ get-expense-proof___ | ✅ |
| "I just got back from a trip, I need to upload all receipts at once" | create-expense-proof___ get-expense-proof___ | ✅ |
| "Finance asked for the receipts from yesterday's dinner — can you attach them?" | create-expense-proof___ get-expense-proof___ | ✅ |
Reconciliation & accounting
| Prompt | Tools | Status |
|---|---|---|
| "Which transactions haven't been categorized yet?" | get-card-transactions___ get-categories___ | ✅ |
| "Group travel expenses this month by user" | get-card-transactions___ get-categories___ | ✅ |
| "Export all March expenses for ERP integration" | get-card-transactions___ | ✅ |
| "Are there banking entries without a category for more than 7 days?" | get-banking-transactions___ get-categories___ | ✅ |
| "Get me the receipt for the Pix I sent yesterday" | get-banking-transactions___ get-banking-transaction-receipt___ | ✅ |
| "Generate the expense report by user for auditing" | get-card-transactions___ get-users___ | ✅ |
| "List transactions where the OCR CNPJ doesn't match the registered supplier" | get-card-transactions___ + supplier tools | ⏳ |
Brazil-specific (tax & compliance)
| Prompt | Tools | Status |
|---|---|---|
| "Are there any expenses that could be deductible for IRPJ this month?" | get-card-transactions___ get-categories___ | ✅ |
| "What is the accumulated IOF on international transactions this month?" | get-card-transactions___ | ✅ |
| "Identify payments to PJ suppliers that may require IRRF withholding" | get-banking-transactions___ + supplier tools | ⏳ |
| "Are there invoices with inconsistent CNPJ vs. the posted category?" | get-card-transactions___ + supplier tools | ⏳ |
| "Which banking outflows this month have no corresponding issued invoice?" | get-banking-transactions___ + supplier tools | ⏳ |
Autonomous multi-tool workflows
| Prompt | Tools | Status |
|---|---|---|
| "For each transaction without a receipt for more than 5 days, create the proof and send the upload URL to the responsible user" | get-card-transactions___ create-expense-proof___ get-users___ | ✅ |
| "Based on current spending pace, in how many days will the card account limit be reached?" | get-card-transactions___ get-credit-card-limit___ | ✅ |
| "Build the complete monthly report by user: spend, active cards, pending receipts, and deviations" | get-users___ get-cards___ get-card-transactions___ get-expense-proof___ | ✅ |
| "After OCR batch closes, consolidate confirmed and inconclusive items and present for review" | create-expense-proof___ get-expense-proof___ + OCR tools | ⏳ |
| "Automatically block cards of users who exceeded the category spending limit" | get-card-transactions___ + policy + blocking tools | ⏳ |
| "Detect split transactions that, summed by supplier, exceed the approval threshold" | get-card-transactions___ + supplier + policy tools | ⏳ |
Authentication & security
The Conta Simples MCP uses OAuth 2.1 with PKCE to authenticate your personal user account:
- On first use, a browser window opens for you to sign in to the Internet Banking
- After authorization, the agent receives a scoped access token
- Tokens are securely stored and automatically refreshed before expiration
Discovery
The agent finds the authorization server from the MCP URL, with no manual configuration:
https://mcp.contasimples.com/.well-known/oauth-protected-resource(RFC 9728) pointsauthorization_serverstohttps://mcp.contasimples.com.https://mcp.contasimples.com/.well-known/oauth-authorization-serverserves the authorization server metadata (RFC 8414), withissueron our domain.
Metadata fields that define how the flow behaves:
| Field | Value |
|---|---|
issuer | https://mcp.contasimples.com |
client_id_metadata_document_supported | true |
code_challenge_methods_supported | ["S256"] |
token_endpoint_auth_methods_supported | ["none"] |
authorization_response_iss_parameter_supported | true |
Agent identification
- Client ID Metadata Document (CIMD) is the primary path. The agent uses as its
client_idthe HTTPS URL of a metadata document it publishes itself, and the server reads that document during authorization. There is no prior registration. - Pre-registration is the alternative for agents without CIMD. See Pre-registered Client ID.
Dynamic client registration is not supported today. Every agent is a public client: there is no client_secret, and the metadata advertises token_endpoint_auth_methods_supported: ["none"].
PKCE
S256 is required. An authorization request without code_challenge returns 400, and one with code_challenge_method=plain also returns 400.
Accepted redirect_uri forms
The request's redirect_uri must match one of the agent's URIs, declared in its CIMD document or registered for the pre-registered client. The matching rule depends on the URI form:
| Form | Example | Matching |
|---|---|---|
| Loopback (RFC 8252 §7.3) | http://localhost:54321/callback | Scheme, host and path. The port is ignored |
| HTTPS (RFC 8252 §7.2) | https://app.example.com/oauth/callback | Exact |
| Private-use scheme (RFC 8252 §7.1) | com.example.app:/oauth/callback | Exact, with no port tolerance |
Because the loopback port is ignored, the agent can open its callback on any free port. No agent needs a fixed port.
Pre-registered Client ID
For agents that do not identify themselves, Conta Simples keeps a pre-registered client_id. It is a public OAuth identifier: it is not a secret, it is not personal, and it is the same for every company. It travels as the client_id parameter of the OAuth flow.
72ic737n3eng9k1l3s02kbeplk
Use this value whenever the agent asks for a required OAuth Client ID. With pre-registration, the agent's redirect_uri must be registered for this client_id. If the agent uses a URI outside that list, contact Support with the URI.
Authorization response
The authorization response always carries the iss parameter with the value https://mcp.contasimples.com (RFC 9207). Check this value before exchanging the code for a token.
Permissions
The tools available to the MCP server depend on the scopes you authorize during login and your user role within the company:
| Scope | Tools enabled |
|---|---|
statements:read | get-card-transactions___, get-banking-transactions___ |
cards:read | get-cards___, get-credit-card-limit___ |
users:read | get-users___ |
categories:read | get-categories___ |
receipts:read | get-expense-proof___ |
receipts:write | create-expense-proof___ |
You can review and revoke MCP access at any time from your Internet Banking settings.
Rate limits
The Conta Simples MCP enforces rate limits to ensure platform stability. When limits are exceeded, the agent will receive a 429 Too Many Requests response and automatically retry with exponential backoff.
Privacy policy
The Conta Simples MCP operates under the Conta Simples privacy framework, which describes how your data is collected, used, stored, and shared when you connect your account to AI agents through this server. Read the full document here: Corporate Privacy and Cookies Policy (PDF, Portuguese).
By authorizing the MCP server to access your account, you agree to the terms described in the corporate privacy and cookies policy linked above. You can revoke access at any time from your Internet Banking settings.
Support
If you run into issues connecting your account or using the Conta Simples MCP, our support team is available through the following channels:
| Channel | Contact | Availability |
|---|---|---|
| (11) 3003-0640 | 24/7 (human support Mon–Sat, 08h–20h) | |
| meajuda@contasimples.com | Response within 1 business day | |
| Phone | (11) 3003-0640 or toll-free 0800-887-0640 | Mon–Fri, 09h30–17h30 |
| Ombudsman | ouvidoria@contasimples.com or 0800-887-0608 | Mon–Fri, 09h–18h |
For MCP-specific issues, include your MCP client name and a description of the error when reaching out. This helps our team resolve your issue faster.
Limitations
- Financial operations (payments, transfers) are not yet available through MCP and are planned for future releases
- The MCP server processes data in real-time and does not maintain local state between sessions