1. Confirm your connection details
Ask Trackly support for the verified MCP connection URL or the local-service setup appropriate to your client. For remote connections, use the provided HTTPS Streamable HTTP endpoint. Local stdio requires the Trackly service to be installed and launched on your machine. Do not assume a public hosted URL or marketplace package exists. Use the connection details supplied for your setup.2. Choose account connection or a private key
Delegated sign-in, where enabled
In a compatible remote MCP client, choose its sign-in or authorization action for the verified Trackly server. The client opens Trackly, where an authorized account owner signs in or creates an account, completes email verification and any required second factor, and reviews the requested connection. General account connection does not require a Trackly umbrella organization and does not move an existing account. The owner consents in Trackly; the client handles the authorization code and tokens privately and returns control to the conversation. Never paste a password, verification code, authorization code, or access/refresh token into chat. Connection consent permits the assistant’s bounded tool access; it does not approve any message. The consent form defaults to a dedicated sandbox key, required send approval, and a daily live-send cap of 100. Review the limits before connecting: select specific sending lists or explicitly allow all current and future account lists. Owners can change the cap; live mode is offered only when enabled. The delegated API surface is limited to the agent workflow; it cannot mint keys, directly send messages, or administer the account. Message history is limited to the connection’s key. An owner can inspect and disconnect grants in Settings → Agent connections. OAuth connection is a separate rollout and is disabled by default. If sign-in is unavailable, use the private-key path below or contact support. A prepared client recipe is not evidence that the production OAuth service is enabled.Private-key fallback
An account owner opens Settings → API Keys and creates a dedicated key:
Copy the once-revealed key directly into your client’s private credential configuration. Never paste it into an assistant conversation, a tool argument, a shared configuration example, or source control. See API key management for rotation and pause controls.
3. Configure your MCP client
For a remote private-key connection, the client suppliesX-Api-Key. For local stdio, the Trackly service receives TRACKLY_API_KEY in its child-process environment. OAuth clients instead manage their bearer credential through sign-in; do not configure both credential headers. None of these methods requires the model to see the secret.
Each client has its own configuration format and environment-variable syntax. Use the instructions matching your installed client:
These are configuration references, not a claim of completed Trackly testing on every client. After changing a process environment, restart the client so it receives the new value; reconnecting an already running process may be insufficient.
Other clients, including Cline, Kilo, Goose, Amp, OpenClaw, Devin, and LM Studio/Bionic, have their own connection settings. Confirm the supported transport, private authentication, account identity, and dashboard-link behavior before using a new client. For Junie skills, install the complete reviewed Trackly skill directory, including its references, using Junie’s skill instructions.
For a custom agent without MCP, use the SMS v2 API with a private, constrained API key and the same hold/approval/readback workflow. A delegated MCP token is audience-bound and must not be forwarded directly to the SMS API.
Building a compatible OAuth client
Use the server’s bearer challenge and protected-resource metadata to discover authorization. The proposed MCP resource ishttps://mcp.tracklysms.com/mcp, with metadata at https://mcp.tracklysms.com/.well-known/oauth-protected-resource/mcp. Its authorization issuer is https://app.tracklysms.com, with metadata at /.well-known/oauth-authorization-server.
When enabled, the authorization server supports S256 PKCE authorization-code flow, trackly.agent scope, client ID metadata documents, and dynamic client registration. The endpoint paths are /oauth/authorize, /oauth/token, /oauth/register, and /oauth/revoke. Use the exact registered redirect and resource identifier. Let the client’s OAuth implementation handle callbacks and private token storage; a copied token in a tool call is not an account connection.
Public clients use no client secret. Registration takes JSON; token and revocation requests use form encoding. Callbacks include state and the issuer’s iss value. Keep the consent flow in the browser where authorization began; it is bound to that browser and the signed-in session. Protocol endpoints allow non-cookie cross-origin clients, while human consent retains its Trackly origin and CSRF checks.
These identifiers describe the integration contract, not deployment availability. Verify metadata and complete an actual client sign-in before advertising compatibility. Keep the dashboard-link fallback for message review even if a client supports interactive URL requests.
Authorization availability requires a completed service rollout, not only a reachable metadata URL. Clients sharing a public network address can share admission limits; respect rejection and retry guidance instead of repeatedly starting sign-in or replaying token requests. Contact support if authorization remains unavailable.
4. Verify the account and sender
Ask the assistant to calltrackly_whoami with no arguments. Check that it reports the intended account, api_key.sandbox: true, and api_key.send_policy.require_confirmation: true. Use this response to determine mode; a key prefix does not reliably identify sandbox keys.
Next, call trackly_list_lists with {"status":"active","limit":50}. The selected list’s phone_number becomes the message’s list_number. Follow returned pagination if necessary. A list’s presence does not prove current send eligibility or recipient consent.
Call trackly_get_setup_status without arguments for read-only setup guidance. It reports stored connection, sender and billing evidence, a bounded recent-hold summary, and links to the next dashboard steps. These signals do not reserve a send, check funding with a payment provider, or prove compliance. Counts can be limited, and an absent recent hold does not prove no earlier message exists. The same guidance appears in Settings → Agent connections.
If there is no eligible sender, complete phone number and list setup in Trackly first. Sandbox also requires an eligible sender and may invoke your configured webhooks. It is not an accountless demonstration mode.
5. Run a reviewed sandbox send
Follow Send SMS with human approval. Verify the rendered content in Trackly, approve the hold, execute it, and read the sandbox result from that hold. Live use additionally requires live-enabled MCP access, a live key, sender readiness, billing eligibility, recipient consent, and an approved send. Switching a key or a prompt does not enable a sandbox-only MCP service to send live messages.Stop or repair a connection
Usetrackly_pause_key to stop the connected key, or pause it in Settings → API Keys. It will stop authenticating after a successful pause. An owner must inspect and resume it in the dashboard; the assistant cannot unpause itself.
For an authentication failure, inspect the key and account in Trackly rather than pasting a replacement credential into chat. Update the client’s private settings after a rotation, restart when necessary, and repeat trackly_whoami before continuing.
For OAuth, an owner can disconnect the grant in Settings → Agent connections and start a fresh connection from the client when needed. Disconnecting access does not recall already queued messages. Read back an uncertain send before reconnecting or attempting another message.
Connection requests expire after ten minutes. If signup or verification takes longer, keep the account you created and start a new connection from the client. A grant lasts at most seven days; clients refresh short-lived access tokens within that period, then need fresh authorization. Refresh credentials are one-use: replay can revoke the connection, so let the client handle recovery and never repeatedly submit an uncertain token exchange manually.