Use MCP with your Apps

Use this guide after connecting an MCP client to synsmarts.

Choose the correct surface

Surface	Use it for
Diagnostics	Status, logs, metrics, traces, history, redacted configuration, reports, and code intelligence
Control	Validated deploy, configuration, resource, access, network, backup, billing, and Team changes
Docs	Searching and reading published synsmarts customer documentation

Starting a diagnostic investigation is allowed on Diagnostics because it produces analysis without changing the App. Operations that change desired state belong on Control.

Don’t connect Control when the automation only needs observation. Separate connections preserve least privilege and prevent a read-only client from discovering mutating tools.

Don’t use Docs as a customer-data surface. It has no App inventory and can’t read Team records, telemetry, configuration, billing data, or customer content.

Discover capabilities for every session

After initialization, call tools/list and use the returned names, descriptions, and input JSON Schemas as the session’s capability contract.

Discovery is filtered, but it isn’t a permanent authorization decision. synsmarts re-authorizes every call against the current connection, person eligibility, Team role, Team, App, permission, and operation policy.

Call tools/list again after access is edited, an App moves between Teams, or a catalog change is announced. Reconnect if the client doesn’t refresh cleanly. Capability-change notifications aren’t available yet. Don’t cache a tool list indefinitely.

Work with multiple Apps

On Diagnostics or Control, call list_apps before choosing an App target. A connection can use either:

• Explicit App access: only named Apps are visible, and each App may have a different permission set.
• Wildcard App access: the same permissions apply to all current and future Apps owned by the Team.

Pass only an App identifier returned by list_apps. When an App moves to another Team, it stops resolving through the old Team’s connection immediately.

A Control connection may contain only Team permissions for billing, membership, helpdesk, or another Team-scoped capability. Those tools don’t require an App target. Use only the Team tools returned by tools/list; an empty list_apps result is valid for intentionally Team-only access.

Call a tool safely

When the tool targets an App, use only an identifier returned by list_apps.

1. Select a tool returned by tools/list.
2. Validate arguments against its JSON Schema.
3. Use the exact App identifier returned by list_apps.
4. For a mutation, include any required idempotency key, expected revision, or typed confirmation.
5. Record the returned request ID, trace ID, and operation ID.

Don’t retry a mutation merely because the client disconnected or timed out. First query the durable operation or current resource state.

Track long-running operations

Deploys, restores, configuration applies, and other long-running actions return a durable operation_id instead of holding the MCP request open.

Use get_operation to read its state, progress, result, and structured error. The operation continues if the MCP session disconnects.

Use cancel_operation only when the operation reports that cancellation is supported. Cancellation is a request to the underlying workflow, not proof that work has already stopped. Poll until the operation reaches a terminal state.

Page through large results

List and search tools return bounded pages. When has_more is true, pass the opaque next_cursor to the same tool with the same filters.

Don’t parse, modify, or reuse a cursor with different filters. Process each page before requesting the next one so the client doesn’t build an unbounded prompt or local result set.

Handle errors and retries

A tool execution error includes stable data such as:

• an error code and operation name;
• impact and a suggested action;
• whether a retry is safe;
• a request ID or trace ID;
• retry_after_seconds when the server requires a delay.

Retry only when the error marks the operation retryable. Respect retry_after_seconds, use bounded exponential backoff with jitter, and keep the same idempotency key for a retry of the same mutation.

Authentication and audience failures occur at the HTTP/OAuth boundary. Obtain a token for the exact Diagnostics, Control, or Docs resource; don’t fall back to a token, API key, or credential intended for another surface.

Change App configuration

Control configuration tools use the same validation, revision, and apply model as the portal, CLI, and API:

1. Call get_site_configuration and retain its revision_token.
2. Submit supported services, resources, or config fields through configure_services with that token, an idempotency key, and confirmation.
3. Save the returned deployment ID and follow it with deploy_status.

The read is a bounded automation projection. It returns core status, shape, resource, service, version, bounds, pending-change, and revision fields. Its service_config contains effective values only. Portal-only form metadata, running_config, and version_options aren’t part of the MCP response.

An accepted configuration change updates the platform-managed App settings file before rendering or changing the running projection. A stale revision, commit conflict, or settings-store outage fails without silently overwriting a newer edit or directly changing the App.

If the committed configuration is correct but the running services have drifted, call reconcile_configuration. Its optional force flag re-drives the committed state even when the applied projection is recorded as current. This operation doesn’t take a revision token because it doesn’t edit the file; it still requires an idempotency key and confirmation.

See How App configuration is applied and App settings file. The full worked service flow is in Configure services.

Respond to access changes

Revoked or expired connections fail closed on the next authorization check. Turning a person’s MCP access off or ending membership revokes all of that person’s human connections without changing Team-owned machine access. Stop automation that repeatedly receives the same authorization failure.

When permissions are intentionally changed:

1. reauthorize if the client requires a new access token;
2. refresh tools/list;
3. call list_apps again on Diagnostics or Control;
4. verify the effective permissions before resuming mutations.

Get help

Include the server name, connection or machine name, tool name, App identifier, request or trace ID, operation ID, and timestamp in a support request. Never include an access token, client secret, raw secret value, or unredacted customer data.

See Get support.