Developer documentation
Corbit SMS · mcp.corbit.sa
Corbit SMS connects AI assistants to a Corbit SMS account (sms.corbit.sa), a Saudi SMS gateway, over the Model Context Protocol (MCP). It sends SMS, bulk and personalized messages and one-time codes, and reads the balance, sender names, groups, templates, the sent-message archive and delivery reports. Every send is shown as a preview first and only goes out after the user confirms it.
Server URL
https://mcp.corbit.sa/mcp · Streamable HTTP, stateless (POST only), version 0.3.12.
Add the server
- Claude (claude.ai and the desktop app): Settings → Connectors → Add custom connector → paste
https://mcp.corbit.sa/mcp→ Connect. A Corbit page opens; paste your API token and approve. - ChatGPT: Settings → Apps & Connectors → Advanced settings → turn on Developer mode → Create → paste
https://mcp.corbit.sa/mcpwith OAuth authentication → sign in on the Corbit page. - Claude Code:
claude mcp add --transport http corbit https://mcp.corbit.sa/mcp, then run/mcpand sign in. Or pass the API token directly:claude mcp add --transport http corbit https://mcp.corbit.sa/mcp --header "Authorization: Bearer <API token>" - Other MCP clients (Cursor, VS Code, …): add a remote HTTP server with the same URL.
Authentication
- OAuth 2.1 with dynamic client registration (RFC 7591), PKCE (S256) and protected-resource metadata (RFC 9728). Metadata:
https://mcp.corbit.sa/.well-known/oauth-authorization-serverandhttps://mcp.corbit.sa/.well-known/oauth-protected-resource. Scopes:sms:send,sms:read,otp. On the consent page the user pastes the Corbit API token (portal: Settings → API keys). Access tokens last 24 hours, refresh tokens 90 days. - Bearer API token: developer tools may send the Corbit API token itself as
Authorization: Bearer <token>. Optional headerX-Corbit-Sender-Names: NAME1,NAME2sets the sender names (the first is the default). - The API key's permissions in the portal still apply: a tool whose permission the key lacks returns a 403 error naming it.
Tools (22)
The five send tools work in two steps: called without confirm=true they return a preview and send nothing; called again with confirm=true and the preview's idempotency_key they send. A retry with the same key returns the first result and is not sent or charged again. dry_run=true also forces a preview.
| Tool | What it does | Type | Arguments (? = optional) | Returns |
|---|---|---|---|---|
send_sms | Send one SMS to one number (Saudi in any format, or international E.164). | Sends SMS (preview, then confirm) | to, message, sender_name?, schedule_at?, allow_duplicate?, confirm?, idempotency_key? | Preview (recipient, parts, balance, warnings, idempotency_key); after confirm: message_id, gateway_status |
send_bulk_sms | Send the same SMS to up to 500 numbers in one request; invalid numbers stop the whole send. | Sends SMS (preview, then confirm) | to[], message, sender_name?, schedule_at?, allow_duplicate?, confirm?, idempotency_key? | Preview (recipients, duplicates removed, parts, balance); after confirm: message_id |
send_to_group | Send one SMS to every number of a saved contact group, in batches of 500. | Sends SMS (preview, then confirm) | group, message, sender_name?, schedule_at?, allow_duplicate?, confirm?, idempotency_key? | Preview (recipients, batches, parts, balance); after confirm: message ids |
send_template | Personalized send: a saved template or text with {{field}} placeholders, own values per recipient (up to 500). | Sends SMS (preview, then confirm) | template | text, vars?, recipients[], sender_name?, confirm?, idempotency_key? | Preview with sample texts; after confirm: message_id |
send_otp | Generate a one-time code, send it by SMS and keep only its hash. | Sends SMS (preview, then confirm) | to, sender_name?, code_length?, ttl_seconds?, language?, app_name?, template? | otp_id, verification_url (Corbit page where the code is entered), expires_at, message_id |
verify_otp | Read the verification result of an otp_id. Takes the otp_id only, never the code. | Read-only | otp_id | verified, or the reason: pending, expired or not_found |
get_balance | Remaining SMS balance (credits). | Read-only | — | balance, checked_at |
get_account | The connected Corbit account. | Read-only | — | name, organization, username, balance |
get_usage | Request limit on the Corbit API and the last balance the gateway saw. | Read-only | — | rate_limit, window_seconds, last_balance |
list_sender_names | Approved sender names of the account and the default one. | Read-only | — | sender_names[], default_sender |
list_groups | Contact groups saved on the account. | Read-only | — | groups[] (name, ref_id) |
create_group | Create a contact group (unique name, 3–255 characters). | Changes account data | name | name, ref_id |
list_group_numbers | Contacts (name and number) of one group. | Read-only | group | count, numbers[] (first 200) |
add_numbers_to_group | Add up to 500 contacts to a group; invalid or duplicate numbers are skipped. | Changes account data | group, contacts[] (number or {number, name}) | added, skipped[] |
list_templates | Saved message templates. | Read-only | — | templates[] (name, text, fields) |
save_template | Create or replace a template ({{field}} and {{field|default}}). | Changes account data | name, text | name, fields[] |
delete_template | Delete a saved template. | Changes account data | name | deleted |
list_sent_messages | Archive of messages sent through the API with this key (90 days, no message text). | Read-only | from?, to?, number?, sender?, with_status?, limit?, cursor? | messages[] (time, sender, numbers, message id, status), next_cursor |
get_sending_stats | Totals for a period from the archive, per sender and per day (Riyadh time). | Read-only | days? (1–90) | send_requests, recipients, accepted/rejected, by_sender, by_day |
get_message_status | Delivery status of one message. | Read-only | message_id | status, normalized_status, final |
get_delivery_report | Delivery status of up to 100 messages, with per-recipient status when available. | Read-only | message_ids[] | messages[], totals (delivered, sent, pending, failed) |
estimate_message | Characters, encoding and SMS parts of a text. Sends nothing. | Read-only | message, recipients? | characters, encoding, parts_per_message, total_parts |
Prompts and cards
- Prompts:
campaign(new SMS campaign with a preview),weekly_report(sending report for N days),otp(send a verification code and read the result). - Cards (MCP Apps,
text/html;profile=mcp-app, light and dark):ui://corbit/send.html(send preview and confirmation),ui://corbit/report.html(delivery report),ui://corbit/account.html(balance and account),ui://corbit/archive.html(sent-message archive). Clients without card support get the same data as text and structured content.
Limits
- Message text: up to 1000 characters. Arabic (UCS-2): 70 characters in one SMS, 67 per part when longer. English (GSM-7): 160 / 153. Each part is charged.
- Up to 500 recipients per send request (groups are sent in batches of 500); up to 100 message ids per delivery report.
- Rate limit: set per account on the Corbit API;
get_usageshows it. A rate-limited call returnsrate_limitedwith the wait time. - Sent-message archive: 90 days, metadata only (no message text). Messages sent from the portal are not included.
- One-time codes: 4–8 digits, valid 60–1800 seconds (default 4 digits, 5 minutes), 5 attempts. The code is entered only on the Corbit verification page.
- Scheduled sends: ISO-8601 date-time; a value without an offset is Saudi time (UTC+3).
- International numbers can cost more than one credit per part; the preview warns about them.
Errors
Tool errors come back as a normal result with isError: true, a readable message and structured fields error, http_status and details. Gateway errors read Corbit gateway error (<code>): <message>, where code is one of unauthenticated, validation, not_found, rate_limited, duplicate, gateway, network. When the gateway returns a request number (X-Gateway-Request-Id) the message ends with (request id …); quote it to support. duplicate means the same text went to the same number(s) moments ago; resending needs allow_duplicate=true.
Help
info@corbit.sa · 920006900 · Support · My connections (see and revoke linked apps) · Privacy · Terms