Skip to content

MCP security

An assistant decides on its own which tool to call, and it can misread a request or be steered by text it reads elsewhere, such as an email or a web page. Set up the server so that a wrong call costs little.

The server can do only what its API key allows. Create a separate key for each assistant setup, with only the scopes in its row:

Use case Scopes What the assistant can’t do
Monitor messages and phones messages:read, devices:read Send anything
Support desk: look up and text one customer messages:send, messages:read, contacts:read Change contacts, run campaigns
Verify a phone number verify:send, verify:check Send any other text, read messages
Maintain the address book contacts:read, contacts:manage Send anything
Draft and review campaigns contacts:read, campaigns:read, campaigns:manage Start a campaign (that needs messages:send too)
Run campaigns end to end contacts:read, campaigns:read, campaigns:manage, messages:send Manage keys, webhooks, members or settings

Add an expiry date and, where the assistant runs on a fixed network, an IP allowlist. See Authentication.

Use an sf_test_ key until you trust the setup. Test messages and campaigns go to the built-in virtual device, move through sent and delivered like real ones, and never reach a phone or cost an SMS. Switch to a live key only when the prompts you use behave as expected. See Sandbox.

Four tools reach real people with a live key: send_sms, send_verification, start_campaign and cancel_campaign (which stops messages people may be expecting).

  • Keep your client’s approval prompt on for these tools. Don’t choose “always allow” for them.
  • Read the arguments in the prompt before you approve: the number, the text, the campaign id.
  • send_sms, start_campaign and cancel_campaign are annotated destructiveHint: true. The campaign tools’ descriptions tell the assistant to confirm with you and to run estimate_campaign first. A client may still run them without asking if you have allowed every tool.
  • send_sms takes an idempotencyKey. An assistant that reuses the key when it retries after a timeout can’t send the same text twice.
  • Read-only tools (list_*, get_*, find_contacts, estimate_campaign) are safe to allow permanently.

The server writes MCP protocol messages to stdout and its own diagnostics to stderr: one line when it connects (smsfabric-mcp: connected (https://api.smsfabric.com)) and a line when it fails to start. It doesn’t log requests, phone numbers, message text or the key.

Your client may keep its own logs of tool calls, with their arguments and results, which include phone numbers and message text. Treat those logs as personal data. Claude Desktop, for example, writes server logs to its logs folder.

Never paste the key into a chat with the assistant. Put it only in the client’s configuration or, better, an environment variable or secret prompt (see Clients).

  1. Rotate a key on a schedule, and at once if a configuration file that holds it was shared or committed. In the portal open Developers → API keys and rotate it, or use apiKeys.rotate.
  2. Put the new secret in the client’s configuration and restart the client. The old secret keeps working for 24 hours, so there is no gap.
  3. If you suspect misuse, revoke the key instead. Requests that use it fail at once.
  4. Check the audit log and the message log for anything the key did that you didn’t expect.

One key per person and per client makes this simple: you revoke one setup without breaking the others.