Connect an agent with MCP
Product guides, public API, webhooks and MCP.
MCP supports number and billing queries, calls, SMS, forwarding, extensions and number purchases. API permissions, ownership checks and account limits also apply.
Connection and authentication
Server: https://mcp.novodid.com/mcp. Transport: Streamable HTTP. Send Authorization: Bearer with your API token. Your client must support custom headers. This server does not provide OAuth; use a Bearer-compatible client.
Create the token in Desenvolvedores → Tokens. Existing tokens do not receive new scopes automatically. Never include tokens in shared prompts, public files or URLs.
TypeScript example
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const client = new Client({ name: 'meu-agente', version: '1.0.0' });
try {
await client.connect(new StreamableHTTPClientTransport(
new URL('https://mcp.novodid.com/mcp'),
{ requestInit: { headers: {
Authorization: `Bearer ${process.env.NOVODID_API_TOKEN}`
} } }
));
const result = await client.callTool({
name: 'search_available_dids',
arguments: { ddd: '11', kind: 'fixed', page: 1, limit: 20 }
});
console.log(result.structuredContent);
} finally {
await client.close();
}Purchasing a number
Use search_available_dids, then quote_did_purchase. Present the price, recurring cycle and conditions. Only after explicit consent call create_did_checkout, using idempotencyKey. Each order accepts one number. Retry uncertain checkout results with exactly the same key and payload; track get_did_order until payment and activation are confirmed.
Creating a QR code or accepting recurring authorization does not prove payment. Pix instructions include a PNG, copy-and-paste code and terminal QR; rendering depends on the client. Card payments use the returned checkout link. Never pay expired instructions or repeat a bank-confirmed payment; contact support with the order ID.
Consent and sensitive data
Confirm the number and destination before changing forwarding. Telephone forwarding requires balance and costs per minute; removing forwarding does not cancel a subscription. SIP credentials require the appropriate scopes and current ownership.
For send_sms, confirm sender, recipient and message. Sending is restricted to replies to an inbound SMS from that recipient during the current ownership's SMS access window. Outbound history or previous ownership does not authorize a conversation. Never automatically retry an uncertain send.
Tools and permissions
get_account
Permission: No additional scope; account:read exposes name and email
Inspect the account and effective token permissions. account:read additionally exposes name and email.
list_dids
Permission: dids:read
List current token-authorized numbers. billing:read exposes billing and cycle; forwarding:read exposes forwarding.
get_did
Permission: dids:read
Inspect didId, status and features. Add billing:read for billing and forwarding:read for routing.
list_forwardings
Permission: forwarding:read
List forwarding for currently owned, token-authorized numbers.
get_did_forwarding
Permission: forwarding:read
Read forwarding for one didId.
set_did_phone_forwarding
Permission: forwarding:phone
Set telephone forwarding with didId and destinationNumber (55 + area code + number). Requires balance and per-minute fees, with no free minutes.
set_did_ip_forwarding
Permission: forwarding:write
Set public-IP forwarding with didId, a public clientIp and clientPort from 1 to 65535.
set_did_sip_forwarding
Permission: forwarding:write
Select an existing authorized extension with didId and sipAccountId. No password is returned.
create_did_sip_forwarding
Permission: forwarding:write + sip:create + sip:credentials:read
Create or reuse the number’s exclusive extension, configure routing and return login, password and server. Supply didId.
delete_did_forwarding
Permission: forwarding:delete
Remove forwarding by didId. Does not cancel the subscription or release the number.
get_did_sip_credentials
Permission: sip:credentials:read
Read the exclusive extension’s login, password and server by didId while eligible SIP forwarding is active.
list_calls
Permission: calls:read
Read calls from current ownership. Filters: didId or did, limit 1–200, page 1–10000, ISO startDate/endDate.
list_sms_messages
Permission: sms:read
Read SMS from the current ownership and SMS access window. Filters: didId or did, direction (inbound/outbound), limit 1–200.
send_sms
Permission: sms:send
Reply to an inbound SMS from this recipient during current SMS access. Supply from, to, text (up to 1600 characters), optional didId. Previous outbound messages, other contacts or prior ownership do not authorize sending. Do not retry automatically after an uncertain result.
search_available_dids
Permission: catalog:read
Search by ddd and kind (fixed/mobile), page starting at 1 and limit 1–100. Search does not reserve inventory.
quote_did_purchase
Permission: catalog:read
Quote one didId with cycle (monthly/semiannually/yearly) and paymentMethod (pix/card). A quote does not create payment.
create_did_checkout
Permission: orders:create
After customer consent, create payment using quoted data, required acknowledgements and idempotencyKey. One number per order.
get_did_order
Permission: orders:read
Read an account-owned order using the returned orderId, including payment instructions while valid.
list_did_orders
Permission: orders:read
List this account’s orders with page and limit, using catalog pagination limits.
Troubleshooting
- 401: check the header, expiration and revocation.
- 403: check scopes, account restrictions, SMS eligibility and security review.
- 404: verify current ownership and use IDs returned for this account.
- 409: read the order or resource before repeating a change.
- 429: respect Retry-After and shared account limits.
The API guide contains numerical limits, payloads and error codes.