MCP connector

Connect Soumow to your AI assistant

Soumow is an Arabic workspace for freelancers: clients, projects, proposals, invoices, appointments and finances. The Soumow connector lets AI assistants such as Claude, ChatGPT, Gemini and Perplexity answer questions about your own Soumow data and prepare drafts for you to review. It never deletes anything, and it never contacts your clients unless you turn that on and approve each message.

Server URLhttps://soumow.com/mcp

Transport: Streamable HTTP · Authentication: OAuth 2.1 with PKCE (S256) and dynamic client registration · Updated November 7, 2026

Before you connect

A Soumow account on the PRO or Business plan. Create one at soumow.com.
An MCP client, such as Claude (web, desktop or mobile), Claude Code, ChatGPT, Gemini, Perplexity, Grok, Cursor or VS Code.
Nothing to install, and no API key. You sign in with your Soumow account and approve access.

Set up

Claude (web, desktop and mobile)

Open Claude → Settings → Connectors. Find Soumow in the directory, or choose Add custom connector and paste https://soumow.com/mcp.
Select Connect. A Soumow page opens: sign in with your Soumow account.
Choose a permission — Read only or Read and create drafts — and select Allow access.
Back in Claude, enable Soumow in a chat and ask a question, for example “Which invoices are overdue?”.

Claude Code

claude mcp add --transport http soumow https://soumow.com/mcp

Then run /mcp, select soumow → Authenticate, and sign in.

ChatGPT

Open ChatGPT → Settings → Apps. Find Soumow in the directory, or (on plans that allow custom apps) turn on Developer mode under Advanced settings, select Create, name it “Soumow”, paste https://soumow.com/mcp and choose OAuth.
Sign in with your Soumow account, choose a permission and select Allow access.
In a chat, enable Soumow from the + menu and ask a question.

Gemini

On the web, open Gemini → Settings → Connectors (or Connected apps). Find Soumow, or add a custom connector with https://soumow.com/mcp.
Sign in with your Soumow account and allow access. Soumow then also works in the Gemini mobile app.
Leave Client ID and Client secret empty: Gemini registers with Soumow automatically.

Perplexity

Open Perplexity → Settings → Connectors → Add custom → MCP connector, name it “Soumow” and paste https://soumow.com/mcp (paid Perplexity plans).
Choose OAuth, sign in with your Soumow account and allow access.

Grok

Open Grok (web or mobile app) → Settings and add a new connector: name it “Soumow”, paste https://soumow.com/mcp and select Connect.
Sign in with your Soumow account, choose a permission and select Allow access. No Client ID or secret is needed.

Other MCP clients

In Soumow, open Settings → Security → AI connection and choose your app (ChatGPT, Gemini, Perplexity, Grok, Cursor, VS Code, Gemini CLI) for step-by-step instructions. Cursor and VS Code have one-click install. Any client that supports remote MCP servers with OAuth can use the server URL above.

Permissions and safety

Read only: Your assistant can read your workspace to answer questions. Nothing is changed.
Read and create drafts: Your assistant can also add clients, tasks, expenses and appointments, mark tasks done, and create proposals and invoices as drafts. Drafts are never sent; you review and send them from Soumow.
Invoice reminder (off by default): if you enable “Allow invoice reminders” in Soumow, your assistant can email a payment reminder for an unpaid invoice. It first shows you the client, amount and reminder type, and sends only after you confirm. Limit: one reminder per invoice per 24 hours. Draft and paid invoices are never reminded.
The connector cannot delete data, move money, or change account, billing or security settings.
Every request runs as your account, with the same permissions and plan limits as the Soumow workspace. You only ever see your own data.
See and revoke connected apps any time in Settings → Security → AI connection → Connected apps. Revoking stops access immediately.
Access tokens expire after 1 hour; refresh tokens after 60 days and rotate on every use. Soumow stores only hashes of tokens. Requests are limited to 60 per minute per connection.

Tools

Each tool carries MCP annotations: read tools are marked readOnlyHint; tools that add or change data are marked destructiveHint and ask for your confirmation before they run.

Read your workspace

Available with both permissions.

Tool	What it does
`get_overview`	Snapshot of the freelancer’s workspace in Soumow: active projects, open proposals, unpaid and overdue invoices, upcoming appointments and this month’s income/expenses. Start here for “how is my business doing” questions.
`search_clients`	Search the clients list by name, company, email or phone. Optional status filter (lead, active, past…). Returns id, contact info, status and project counts.
`get_client`	Full details of one client by id, including notes and linked work.
`list_projects`	List projects with status, client, progress, due date, budget and task counts. Filter by status or client name text.
`get_project`	One project by id with its tasks.
`list_proposals`	List price proposals with number, client, state (draft, sent, accepted, rejected, expired), total and validity date.
`list_invoices`	List invoices with number, client, total, paid, amount due, due date and state. Use filter “unpaid” or “overdue” for collection questions.
`list_appointments`	Appointments between two dates (YYYY-MM-DD, site time zone). Defaults to today through the next 7 days.
`finance_summary`	Income and expense totals for a month (YYYY-MM, default current month) per currency, top expense categories and the latest entries.

Create and update (drafts)

Available with “Read and create drafts”. Nothing is sent to clients.

Tool	What it does
`create_client`	Add a new client (status lead). Only name is required.
`add_task`	Add a task to a project by project id (use list_projects to find it).
`create_proposal_draft`	Create a DRAFT price proposal (never sent to the client). The freelancer reviews and sends it from Soumow. Write content in the language the client should read (usually Arabic).
`create_invoice_draft`	Create a DRAFT invoice with line items (never sent). The freelancer reviews and sends it from Soumow.
`add_expense`	Record an expense in Earnings & Expenses. Category is auto-detected when omitted.
`update_task`	Mark a project task done or not done, rename it, or set its due date. Get task ids from get_project.
`add_appointment`	Add an appointment to the freelancer’s calendar (site time zone). Does not email the client. Returns a warning when it overlaps another appointment.

Send with your approval

Hidden unless you enable invoice reminders in Soumow. Always previews first and requires your confirmation.

Tool	What it does
`send_invoice_reminder`	Email the client a payment reminder for an unpaid invoice, in the freelancer’s reminder tone. Two steps: call WITHOUT confirm to get a preview, show it to the user and ask for explicit approval; only after the user says yes, call again with confirm=true. Never set confirm=true on your own. One reminder per invoice per 24 hours.

Examples

“Which of my invoices are overdue, and how much is outstanding in total?”Uses list_invoices with the overdue filter and sums the amounts due by currency.
“What appointments do I have tomorrow?”Uses list_appointments for tomorrow’s date and lists times, clients and meeting types.
“How did my business do in October? Compare income and expenses.”Uses finance_summary for 2026-10 and get_overview for open work.
“Create a draft invoice for Ahmed: logo design, 1,500 SAR, due in 14 days.”Uses search_clients to find Ahmed, then create_invoice_draft. The invoice stays a draft until you send it from Soumow.
“Add a task “Send final files” to the online store project, due Thursday.”Uses list_projects to find the project, then add_task.

Troubleshooting

The sign-in page says the connection link is invalid or expired.: Start the connection again from your app. Links are valid for a few minutes and work once.
“AI connection is available on PRO and Business plans.”: Upgrade in Soumow (Settings → My subscription), then connect again. If your subscription lapses, the connection pauses and resumes when you renew — no setup needed.
The assistant can read but cannot create anything.: You approved “Read only”. Revoke the app in Connected apps and connect again with “Read and create drafts”.
The invoice reminder tool is missing.: Enable “Allow invoice reminders” in Settings → Security → AI connection.
Requests fail after a while.: Your app refreshes access automatically. If access was revoked or the refresh token expired (60 days unused), connect again.
“Too many requests”.: Wait a minute; each connection allows 60 requests per minute.
Your app asks for a Client ID and Client secret.: In Soumow’s AI connection window, choose the app, paste its redirect URI under “Client ID and Client secret”, and copy the generated values back into the app.

Data and privacy

The connector reads only the Soumow data of the account that signed in, when you ask. We do not receive or store your conversations with any AI assistant. Read the full connector privacy policy and the Soumow privacy policy.

Support and security

We answer connector questions in Arabic and English, usually within one business day.

Contact form: soumow.com/contact/
Security reports: use the same channel with the subject “Security”. We acknowledge reports within 2 business days, investigate them, and tell you the outcome. Please do not test against accounts you do not own.