> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an AI Assistant to Trackly MCP

> Connect any compatible AI assistant to Trackly SMS with delegated sign-in or a private API key, then verify sandbox mode and human approval.

Start with an existing Trackly account and an MCP-capable client. If you are a new customer, follow [agent-assisted account setup](/agents/onboarding) first.

## 1. Confirm your connection details

Ask [Trackly support](/resources/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](https://app.tracklysms.com/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](https://app.tracklysms.com/settings/api-keys) and creates a dedicated key:

| Setting               | Starting configuration                                                                             |
| --------------------- | -------------------------------------------------------------------------------------------------- |
| Name                  | Identify the assistant and the person responsible for it.                                          |
| Sandbox mode          | Enable it for setup and the first approved-send test.                                              |
| Require send approval | Enable it so SMS must go through Trackly's approval workflow.                                      |
| Allowed sending lists | Select the lists the assistant needs. An empty restriction allows all account lists.               |
| Daily send cap        | Set an appropriate limit for live sends. Sandbox simulations do not consume the live-send counter. |

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](/account/api-keys) for rotation and pause controls.

## 3. Configure your MCP client

For a remote private-key connection, the client supplies `X-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:

| Client                                                                                                                                                                                        | Configuration detail to check                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| [Codex](https://developers.openai.com/codex/mcp)                                                                                                                                              | Use `env_http_headers` to supply the custom `X-Api-Key` header from a private environment variable.                          |
| [Claude Code](https://code.claude.com/docs/en/mcp)                                                                                                                                            | HTTP MCP server entries support headers and environment references; keep the setup in user-scoped private configuration.     |
| [Cursor](https://cursor.com/docs/mcp)                                                                                                                                                         | Check remote header syntax; configure desktop and cloud connections separately.                                              |
| [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/)                                                                                                                                    | Use its Streamable HTTP configuration and retain client confirmation settings.                                               |
| [Hermes](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)                                                                                                                  | Name the server `trackly` if using the companion gate, and retain the dashboard-link fallback.                               |
| [OpenCode](https://opencode.ai/docs/mcp-servers/)                                                                                                                                             | Stable V1 and [V2](https://opencode.ai/v2/docs/mcp-servers) use different configuration shapes. Match the installed version. |
| [Junie CLI](https://junie.jetbrains.com/docs/junie-cli-mcp-configuration.html)                                                                                                                | Configure the verified URL with `mcpServers.trackly.url`; use `/mcp` → Trackly → Authorize where OAuth is enabled.           |
| [Junie IDE plugin](https://junie.jetbrains.com/docs/junie-plugin-mcp-settings.html)                                                                                                           | Use Tools → Junie → MCP Settings. Its authentication capabilities differ from Junie CLI; verify the installed surface.       |
| [Copilot in VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)                                                                                                   | Use the `servers` map in MCP configuration, with `type: "http"`. Follow its authorization prompt.                            |
| [Copilot CLI](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference)                                                                                       | Add the verified HTTP server and use `/mcp auth trackly`; CLI settings differ from VS Code.                                  |
| [Antigravity](https://www.antigravity.google/docs/mcp)                                                                                                                                        | Current configuration uses `mcpServers.trackly.serverUrl`. Complete any authorization-code handoff in private settings.      |
| [ChatGPT](https://developers.openai.com/plugins/build/auth) / [Claude remote connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) | Use the product's hosted connector/plugin account connection. Local CLI configuration does not configure this surface.       |

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](https://junie.jetbrains.com/docs/agent-skills.html).

For a custom agent without MCP, use the [SMS v2 API](/api-reference/v2/overview) 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 is `https://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 call `trackly_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](/concepts/phone-numbers) 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](/agents/send-with-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

Use `trackly_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.