@honkio/mcp

HonkIO MCP Server

Model Context Protocol (MCP) server for HonkIO, the Canadian SMS API. It lets an AI agent send SMS, run phone verification, manage Canadian numbers, and handle CASL compliance through natural language.

47 tools, 4 resources, and 5 guided prompts, all backed by the live HonkIO REST API. Use it two ways: point your client at the hosted endpoint at https://mcp.honkio.ca/mcp, or run it locally with npx. Both talk to the same API with the same key.

Requirements

• A HonkIO account and API key
• For the local npx route only: Node.js 20 or newer

1. Get an API key

Sign in at https://honkio.ca/dashboard/keys and copy a key:

Prefix	Mode	Behaviour
mk_test_…	Test	Messages are simulated as delivered. No SMS is sent and nothing is charged.
mk_live_…	Live	Real SMS, real Canadian numbers, real charges against your balance.

Start with a test key. It works before your account's first top-up and can't spend anything: sends and verifications are simulated for free, and a test send still runs the same compliance checks a live one does (consent, opt-out, allow/deny lists, reserved and undeliverable destinations), just without requiring you to own the from number. A handful of tools that touch live money or data (provisioning or releasing a number, writing or reading a webhook's dead letters, erasure, and volume/allowance requests) need a live key and answer LIVE_KEY_REQUIRED from a test one. Switch to a live key when you want real delivery.

Live sending also requires that the account owner has completed phone verification, and that you have provisioned at least one number to send from.

2. Connect your AI tool

There are two ways in. The hosted endpoint needs nothing installed and is the right choice for claude.ai connectors, the Claude Messages API, and any client that speaks Streamable HTTP. The local route runs the same server on your machine through npx.

In every example below, put your own key where it says mk_test_YOUR_KEY_HERE.

Hosted endpoint

The key travels in a header on every request, so never paste it into a file you commit. The JSON examples read it from an environment variable.

Claude Code

claude mcp add --transport http honkio https://mcp.honkio.ca/mcp \
  --header "Authorization: Bearer mk_test_YOUR_KEY_HERE"

Prefer to sign in rather than paste a key? Add the endpoint without a header and run /mcp inside Claude Code: a browser window opens on honkio.ca where you approve the connection and choose live or test mode. A live connection also asks for your account password. The connection shows up on your API keys page as OAuth: Claude Code, and revoking it there disconnects the agent.

claude mcp add --transport http honkio https://mcp.honkio.ca/mcp

Or in a shared .mcp.json, with the key coming from HONKIO_API_KEY in your shell:

{
  "mcpServers": {
    "honkio": {
      "type": "http",
      "url": "https://mcp.honkio.ca/mcp",
      "headers": { "Authorization": "Bearer ${HONKIO_API_KEY}" }
    }
  }
}

Cursor (.cursor/mcp.json or ~/.cursor/mcp.json)

{
  "mcpServers": {
    "honkio": {
      "url": "https://mcp.honkio.ca/mcp",
      "headers": { "Authorization": "Bearer mk_test_YOUR_KEY_HERE" }
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "honkio": {
      "type": "http",
      "url": "https://mcp.honkio.ca/mcp",
      "headers": { "Authorization": "Bearer mk_test_YOUR_KEY_HERE" }
    }
  }
}

Claude Messages API (no MCP client needed)

{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "messages": [{ "role": "user", "content": "List my HonkIO phone numbers." }],
  "mcp_servers": [
    { "type": "url", "url": "https://mcp.honkio.ca/mcp", "name": "honkio", "authorization_token": "mk_test_YOUR_KEY_HERE" }
  ],
  "tools": [{ "type": "mcp_toolset", "mcp_server_name": "honkio" }]
}

Send that with the anthropic-beta: mcp-client-2025-11-20 header. The endpoint also accepts the key as X-API-Key if your client cannot set Authorization.

Local with npx

npx fetches the server on first use and caches it. Needs Node.js 20 or newer.

Claude Code

claude mcp add honkio \
  --env HONKIO_API_KEY=mk_test_YOUR_KEY_HERE \
  -- npx -y @honkio/mcp

Or in .mcp.json (keep the real key out of git, see Keeping your key out of git):

{
  "mcpServers": {
    "honkio": {
      "command": "npx",
      "args": ["-y", "@honkio/mcp"],
      "env": { "HONKIO_API_KEY": "mk_test_YOUR_KEY_HERE" }
    }
  }
}

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), same mcpServers block as above, then restart Claude Desktop.

Cursor: .cursor/mcp.json or ~/.cursor/mcp.json, same mcpServers block.

VS Code (.vscode/mcp.json)

{
  "servers": {
    "honkio": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@honkio/mcp"],
      "env": { "HONKIO_API_KEY": "mk_test_YOUR_KEY_HERE" }
    }
  }
}

3. Confirm it works

Ask your agent:

List my HonkIO phone numbers.

• A list (or an empty list) means you are connected.
• Error [UNAUTHORIZED]: Invalid or missing API key. means the key is wrong, missing, or has been revoked.

To check the server outside any AI tool:

HONKIO_API_KEY=mk_test_YOUR_KEY npx -y @honkio/mcp

It should start and wait silently on stdin. An MCP server speaks JSON-RPC over stdio, so no output is the healthy state. Press Ctrl-C to exit. If it exits immediately with an error, the message tells you what is wrong.

To check the hosted endpoint outside any AI tool:

curl -s https://mcp.honkio.ca/healthz
curl -s -i -X POST https://mcp.honkio.ca/mcp | head -3

The first returns {"ok":true,"version":"..."}. The second, with no key, returns 401 and a WWW-Authenticate: Bearer header, which is the endpoint telling you where the key goes.

Environment variables

Variable	Used by	Required	Description
HONKIO_API_KEY	local npx	Yes	Your API key (mk_live_… or mk_test_…). The stdio server refuses to start without it. The hosted endpoint takes the key from the request header instead.
API_URL	both	No	Override the API base URL. Defaults to https://api.honkio.ca. Only needed for self-hosting or local development. The pre-1.5 name HONKIO_API_URL still works.
PORT	hosted	No	Port for honkio-mcp-http. Defaults to 8080.
MCP_ALLOWED_ORIGINS	hosted	No	Comma-separated browser origins allowed to call the endpoint. Empty by default, which refuses any request carrying an Origin header. Command-line and server-side clients send none and are unaffected.
MCP_RATE_LIMIT_PER_MINUTE	hosted	No	Requests per minute allowed from one client address. Default 300. Beyond it the endpoint answers 429 with Retry-After.
MCP_AUTH_FAILURES_PER_MINUTE	hosted	No	Refused requests (bad or missing key, bad Origin, malformed body) per minute allowed from one client address before the address is locked out for the rest of the minute. Default 10.
MCP_TRUSTED_PROXIES	hosted	No	How many proxy hops in front of the process append to X-Forwarded-For. The client address is read that many entries from the right. Railway's edge is one hop, the default. Set 0 when nothing sits in front.
MCP_SERVICE_KEY	hosted	No	This service's key at the HonkIO API (the API's MCP_SERVICE_KEY). Lets the endpoint accept OAuth access tokens, so clients can sign in instead of pasting a key. Unset means API keys only.
MCP_PUBLIC_URL	hosted	No	The public URL access tokens are bound to. Default https://mcp.honkio.ca/mcp.

Keeping your key out of git

.mcp.json and .vscode/mcp.json are usually committed. An API key pasted into one is a live credential in your repository history. Either keep those files untracked, or reference an environment variable your shell already exports and add the file to .gitignore.

If a key does leak, revoke it immediately at https://honkio.ca/dashboard/keys. A revoked key stops working at once.

Tools

Messages

Tool	Description
send_sms	Send an SMS from one of your numbers. Enforces CASL consent unless overridden. Pass idempotency_key when retrying. A reserved exchange (555-XXXX, N11, test codes) is refused for free with 422 RESERVED_DESTINATION.
list_messages	List messages, filterable by number, status, direction and date.
get_message	Full detail for one message, including delivery status and cost.

Both directions are billed per part, the way the carrier splits the body: sending an SMS charges per part, and receiving one on a provisioned number charges the inbound per-part cost. get_pricing returns both figures. Inbound charges happen automatically whenever someone texts your number, independent of any tool call.

Phone verification (OTP)

Tool	Description
start_verification	Send a one-time code to a phone number.
check_verification	Submit a code to verify it.
get_verification	Status of a single verification attempt.
list_verifications	List verification attempts.

On a live key, verification is billed per message segment plus a per-verification surcharge. get_pricing returns the current figure. On a test key nothing is sent and nothing is charged, and the code is always 000000, padded to the requested length. Every verification carries a mode of LIVE or TEST, so you never have to infer which happened.

Pricing

Tool	Description
get_pricing	Current per-segment outbound SMS cost, per-segment inbound SMS cost, verification upcharge, phone-number first-month/monthly rent, and the one-time activation fee, in CAD cents.

Prices are set at runtime and change without a release. Read them rather than hardcoding them.

Phone numbers

Tool	Description
list_area_codes	Provinces HonkIO has numbers in, and the active area codes within each.
search_phone_numbers	Search available Canadian numbers, filtered by up to 5 area codes.
provision_phone_number	Purchase a number. Charges the first month plus a one-time activation fee, then monthly rent. Live keys only.
list_phone_numbers	List the numbers on your account.
get_phone_number	Detail for one number.
release_phone_number	Release a number and stop its recurring rent. Live keys only.
request_number_allowance	Ask to hold more numbers than the current per-account limit. Live keys only.
list_number_allowance_requests	List past and pending allowance requests.

CASL compliance

Tool	Description
record_consent	Record express or implied consent.
list_consents	List consent records.
check_consent	Check whether a number has valid consent.
revoke_consent	Revoke consent for a number.
record_opt_out	Record an opt-out manually.
list_opt_outs	List opt-out records.

DNCL: not available yet

Tool	Description
check_dncl	Returns 501 DNCL_COMING_SOON.
batch_check_dncl	Returns 501 DNCL_COMING_SOON.

CRTC Do Not Call List checking is not live. dncl_exemptions on send_sms is accepted but not yet acted upon.

Webhooks

Tool	Description
create_webhook	Register an endpoint for delivery receipts and inbound messages. Live keys only.
list_webhooks	List registered webhooks.
get_webhook	Detail for one webhook.
update_webhook	Change a webhook's URL or subscribed events. Live keys only.
delete_webhook	Remove a webhook. Live keys only.
list_webhook_deliveries	Delivery attempts for a webhook, for debugging.
list_webhook_dead_letters	Deliveries that exhausted their retries. Live keys only, since a dead letter carries the failed payload.
replay_webhook_dead_letter	Retry a dead-lettered delivery. Live keys only.
discard_webhook_dead_letter	Drop a dead-lettered delivery. Live keys only.
reactivate_webhook	Re-enable a webhook disabled by repeated failures. Live keys only.

Sending limits

Tool	What it does
get_send_limit	Daily cap (rolling 24 h), usage, the per-recipient cap (recipient_rate_per_hour / recipient_rate_per_day), probation status, any active pause, and past volume requests.
request_send_limit	File a "request a higher volume" for staff review once probation has ended. Live keys only.
list_send_limit_requests	List past and pending volume requests.
get_topup_allowance	How much credit can be added right now under the balance and 30-day top-up caps.

New accounts can send 250 live messages per rolling 24 hours; 30 days after the first live send they can request more. Identical messages to many recipients, per-number rate, link shorteners, and unusually high opt-out or failure rates are also limited. See honkio.ca/docs#limits. Refused sends return DAILY_LIMIT_REACHED, FANOUT_LIMIT_REACHED, NUMBER_RATE_LIMITED, RECIPIENT_RATE_LIMITED (30 an hour / 100 a day to one number), SENDING_PAUSED, UNDELIVERABLE_NUMBER (three consecutive carrier failures list a number for 90 days), NOT_A_MOBILE_NUMBER (a landline or VoIP destination, refused before sending), RESERVED_DESTINATION (a reserved exchange such as 555-XXXX, N11 or a carrier test code, refused in both modes) or LINK_SHORTENER_BLOCKED with details.

Account and keys

Tool	Description
whoami	The account the API key belongs to (id, name, balance, status) and its list of API keys. Does not say which key you are calling with.
get_account	Account detail and credit balance.
update_account	Update the account name.
get_usage	Usage for a billing period, including live delivery health (delivery: delivered, failed, undelivered, pending, failureRatePct; byNumber: the same per sending number).
list_transactions	Balance transaction ledger (top-ups, refunds, rent, provisioning and verification fees), newest first.
create_api_key	Issue a new live or test key, with permissions no broader than the calling key's own.
rotate_api_key	Replace a key, invalidating the old value.
revoke_api_key	Revoke a key immediately.

account_id is optional on all of these. Omit it and the server resolves your account from the API key, so "show my usage for this month" just works. Pass one explicitly only if you are deliberately targeting a different account. Use whoami if you want to see the id itself.

PIPEDA

Tool	Description
request_erasure	Execute a right-to-erasure request for a phone number. Live keys only.

Not covered here

The REST API has more surface than this package exposes as tools. Reachable directly through the API (not through MCP):

• Contacts, contact groups, and their broadcast sends (/v1/contacts, /v1/contact-groups)
• Allow/deny lists, both the standalone contact lists (/v1/lists) and the ones attached to an API key (/v1/accounts/:id/api-keys/:keyId/lists)
• Owner phone verification (/v1/accounts/:id/phone-verification and its /confirm), the one-time step a live account needs before it can send
• An API key's default-deny flag (PATCH /v1/accounts/:id/api-keys/:keyId/default-deny)

See honkio.ca/docs for the full REST reference.

Resources

Readable by MCP clients that support resources:

URI	Contents
honkio://messages	20 most recent messages
honkio://phone-numbers	Your provisioned numbers
honkio://consents	Active CASL consent records
honkio://webhooks	Registered webhook endpoints

Prompts

Guided multi-step workflows:

Prompt	What it walks through
send_compliant_sms	Check consent, then send
provision_canadian_number	Search, then purchase
setup_webhooks	Register event notifications
compliance_audit	Full compliance check on a number
handle_erasure_request	Process a PIPEDA erasure request

Things to try

Find me an available Toronto (416) number and tell me what it costs before buying anything.

Check whether +1514XXXXXXX has valid CASL consent, and if it does, text them that
their appointment is confirmed for 2pm tomorrow.

Start a phone verification for +1604XXXXXXX, then check the code 123456 against it.

Set up a webhook at https://myapp.ca/webhooks/honkio for delivery receipts and
inbound messages.

Show me any webhook deliveries that failed and ended up in the dead-letter queue.

Spending money by accident

Two tools move real money on a live key:

• provision_phone_number charges the first month's rent plus a one-time activation fee, together, and starts monthly rent. Rent keeps accruing until you call release_phone_number; the activation fee is not refunded on release.
• send_sms and start_verification charge per SMS part against your balance, counted the way the carrier splits the body (typographic quotes and dashes are smart-encoded to GSM-7; emoji force Unicode parts). The charge is settled to the carrier's part count after the send. A send the carrier rejects outright costs nothing, and so does a send to a reserved exchange (555-XXXX and similar), which is refused here; a message the carrier accepts but cannot deliver keeps its charge. A body over 10 parts is refused with 422 MESSAGE_TOO_LONG before any charge. start_verification adds a per-verification surcharge on top. get_pricing tells you what each costs right now.

A third charge is not tool-triggered at all: inbound SMS is billed per segment the moment a carrier delivers it to one of your provisioned numbers, whether or not you ever call a tool. Traffic to a number you provisioned draws down your balance on its own (STOP/START/HELP replies are not charged), and a received message is debited even when the balance cannot cover it: the balance goes negative and sends are frozen until the next top-up.

Agents act on instructions that can be vaguer than you intended. If you are exploring, use a test key: sends and verifications are simulated and charge nothing, but buying or releasing a number, changing webhooks and running erasure need a live key.

A test-mode send still comes back with status DELIVERED, because it simulates a successful delivery. That is not a claim that a phone received anything. The mode field on the response, LIVE or TEST, is the one that tells you whether an SMS actually left the building.

Canadian compliance

• CASL: commercial messages need consent on record. Use record_consent before sending; send_sms enforces it unless you pass skip_consent_check, which only a test-mode key can do (a live key gets 403 FORBIDDEN). Express consent does not expire; implied consent expires two years after the last transaction.
• DNCL: CRTC Do Not Call List checking is not available yet and is not enforced.
• PIPEDA: customer data is stored in Canada (ca-central-1). Request processing currently runs on infrastructure outside Canada, so data crosses the border in transit; see the privacy policy for the full disclosure. Use request_erasure for right-to-erasure requests.

Troubleshooting

Symptom	Cause and fix
UNAUTHORIZED	Key is wrong, revoked, or never reached the server. Check the env block, or the Authorization header on the hosted endpoint.
Tools do not appear in the agent	The client did not start the server. Restart the client, and check that npx is on its PATH, since GUI apps do not always inherit your shell's PATH.
First start is slow, or times out once	npx downloads the package on first use. Run npx -y @honkio/mcp once in a terminal to warm the cache, then restart your client.
npm ERR! 404	Usually an npm registry override or a private proxy. Check npm config get registry.
PAYMENT_REQUIRED	A live key needs the account's first top-up before use; a test key works without one.
LIVE_KEY_REQUIRED	The tool you called touches live money or data. Test keys are a sandbox and can't reach it; use a live key.
ACCOUNT_NOT_VERIFIED	Live sending needs the account owner's phone verified. Do it in the dashboard.
DNCL_COMING_SOON	Expected, answered as 501. DNCL checking is not live yet.
Server starts then exits silently	That is normal when nothing is attached to stdin. It only means something is wrong if it prints an error.

Development

To work on the server rather than just use it:

git clone https://github.com/jeffcaldwellca/honkio
cd honkio/mcp
npm install

npm run dev        # run from source with tsx, no build step
npm run typecheck  # types only
npm run build      # compile to dist/

Point a local checkout at your own API with API_URL=http://localhost:3000, and at a local build by using node /path/to/honkio/mcp/dist/index.js as the command in your client config instead of npx.

dist/ is gitignored and the published tarball is built from it, so prepublishOnly rebuilds on every npm publish, so never publish without letting it run.

Running the hosted entry yourself

The same package ships honkio-mcp-http, the process behind mcp.honkio.ca:

PORT=8080 API_URL=https://api.honkio.ca npx -y -p @honkio/mcp honkio-mcp-http

It answers GET /healthz and POST /mcp, verifies each caller's key against the API once a minute, rate-limits each client address (see the environment table), and serves both the 2025 handshake protocol and the 2026-07-28 revision. There is a Dockerfile and a railway.toml in this directory for hosting it.

Publishing to the MCP Registry

server.json describes both the npm package and the hosted endpoint for the official MCP Registry under the ca.honkio namespace, which is verified by a DNS record on honkio.ca. The registry entry is live; these are the steps to repeat for a new release.

The publisher is a Go binary, not an npm package:

brew install mcp-publisher

Generate the signing key once. macOS ships LibreSSL, whose genpkey has no Ed25519, so use Node:

node -e "
const {generateKeyPairSync}=require('crypto'),fs=require('fs');
const {publicKey,privateKey}=generateKeyPairSync('ed25519');
const pub=publicKey.export({format:'der',type:'spki'});
fs.writeFileSync('mcp-registry.pem',privateKey.export({format:'pem',type:'pkcs8'}),{mode:0o600});
console.log('TXT value: v=MCPv1; k=ed25519; p='+pub.subarray(pub.length-32).toString('base64'));
"

Publish that value as a TXT record on the apex of honkio.ca (host @). The key file is gitignored; keep it, since every future release signs with it.

Then, for each release, after npm publish and with a matching version in server.json:

PRIV=$(node -e "
const {createPrivateKey}=require('crypto'),fs=require('fs');
const der=createPrivateKey(fs.readFileSync('mcp-registry.pem')).export({format:'der',type:'pkcs8'});
console.log(der.subarray(der.length-32).toString('hex'));
")
mcp-publisher login dns --domain honkio.ca --private-key "$PRIV"
mcp-publisher publish

The registry checks that the published npm package carries a matching mcpName field, so npm publish has to happen first.

The serverJson test pins server.json to package.json, so a version bump that forgets one of them fails npm test.

License

MIT