MCP reference
synsmarts customer MCP targets MCP protocol 2026-07-28 over remote
Streamable HTTP and negotiates compatibility with current Claude Code and Codex
clients. Each server exposes one HTTPS /mcp endpoint.
Servers
Section titled “Servers”| Server | Endpoint | OAuth resource and audience | Capability |
|---|---|---|---|
| Diagnostics | https://mcp-diagnostics.synsmarts.io/mcp | https://mcp-diagnostics.synsmarts.io | Read-only observation and analysis |
| Control | https://mcp-control.synsmarts.io/mcp | https://mcp-control.synsmarts.io | Validated customer mutations and operation status |
| Docs | https://mcp-docs.synsmarts.io/mcp | None; anonymous public access | Search and read published customer documentation |
Diagnostics and Control tokens are audience-bound and rejected by the other protected server before discovery. Docs doesn’t request or consume a token.
Authentication
Section titled “Authentication”| Principal | Authorization |
|---|---|
| Human | OAuth authorization code with PKCE |
| Agent, bot, or service account | Team-owned OAuth client credentials |
Access tokens are short-lived. For a human, browser consent creates the persistent connection record and binds the authorization code, access token, and rotating refresh-token chain to it. OAuth client registration identifies Claude Code or Codex; registration alone grants no Team, App, permission, or data access.
Claude Code uses a trusted Client ID Metadata Document. Current Codex uses the deprecated Dynamic Client Registration compatibility endpoint as a public native client. Both use authorization code with PKCE S256 and variable-port loopback callbacks without customer configuration.
For a machine flow, the static credential belongs to one Team-owned record and mints access tokens; it isn’t an App credential. Team owners and admins create and manage machine access on the Team’s MCP access page. A machine secret is displayed once; losing it requires rotation. The same page lists and revokes human connections.
Team access records
Section titled “Team access records”Each Team membership has an MCP eligibility switch that defaults off. Enabling it permits OAuth consent but grants no permission by itself. Turning it off or ending membership revokes all of that person’s human connections and token chains. Machine access remains Team-owned and is unaffected by its creator leaving.
Human role ceilings are owner/admin for allowed Team and App permissions,
developer for App-scoped Diagnostics and Control, and billing for Diagnostics
billing.read only.
Each internal access record stores:
| Field | Contract |
|---|---|
| Connection ID | Stable internal identifier used for audit and revocation |
| Name | Customer-readable connection or machine name |
| Team | One immutable owning Team |
| Principal | Type, required display name, and optional external identity reference |
| Surface | Exactly one of diagnostics or control |
| Team permissions | Optional non-App permissions |
| App permissions | Either a wildcard permission set or explicit App-to-permission rows |
| Status | pending, active, revoked, or expired |
| Lifecycle | Creator, creation, use, rotation, expiration, and revocation metadata |
Wildcard and explicit App modes can’t be mixed in one Diagnostics or Control connection. Wildcard mode applies the same permissions to all current and future Apps owned by the Team. Explicit mode can assign different permissions to selected Apps. Docs has no connection record or App permissions.
Discovery
Section titled “Discovery”Use server/discover to negotiate the protocol version and capabilities.
The tool list returned by tools/list is authoritative for the connection and
contains only tools for which it has permission on at least one currently resolvable Team
or App target.
list_apps is available on Diagnostics and Control. It returns only resolvable Apps and
their effective permissions for that server. Missing, foreign-Team, moved, and
ungranted App identifiers return the same leak-safe not-found result.
Docs has no App inventory or Team/App data operation.
After an access change, reconnect or call tools/list again to refresh
discovery. Capability-change subscriptions aren’t available yet. The API
re-authorizes every call, so discovery doesn’t preserve access after a
connection is revoked, its person is disabled, or its role or permissions
change.
Permission vocabulary
Section titled “Permission vocabulary”Permissions are explicit strings. One broad label doesn’t silently imply unrelated access.
Diagnostics permissions:
logs.read,audit.read,metrics.read,traces.readstatus.read,config.read,deployments.readbackups.read,dns_tls.read,database_queries.readfindings.read,diagnostics.run,code.readbilling.read(Team-level)
Control permissions:
operations.readdeployments.write,config.write,scale.writeservices.operate,database_queries.terminate
Every permission you can select unlocks at least one tool on its surface. When a new capability family ships, its permission appears in the consent screen in the same release — you never consent to access that doesn’t do anything yet.
The capability catalog owns the exact permission-to-operation mapping.
list_apps is automatic on Diagnostics and Control and isn’t an assignable
permission.
Diagnostics capability families
Section titled “Diagnostics capability families”Diagnostics covers inventory, status, logs, metrics, traces, configuration,
history, analysis, and permitted code intelligence. The authoritative tool
names and schemas are returned by tools/list.
Starting an analysis workflow requires diagnostics.run and creates an
operation record, but it doesn’t change the App.
Control capability families
Section titled “Control capability families”Control covers deploy lifecycle, desired configuration, resources and services, bounded database operations, access, network and security, data protection, and permitted Team product controls.
The exact tools available to a client come from tools/list; capability family
names aren’t tool names.
Docs capability family
Section titled “Docs capability family”Docs exposes bounded search and read operations over the published customer documentation corpus. It can’t read internal docs, ADRs, plans, source repositories, Team records, Apps, telemetry, configuration, billing data, or customer content. It is anonymous and independently rate-limited by source IP, operation cost, and repeated-call behavior.
Input and result contract
Section titled “Input and result contract”- Tool arguments use strict JSON Schema.
- App identifiers address the
{app}segment of the resource URL; the authenticated connection must authorize that addressed App. - Lists use opaque cursor pagination with
next_cursorandhas_more. - Tool results are bounded to approximately 32 KiB unless an operation has a smaller limit.
- Binary artifacts use access-checked download operations rather than embedded bytes.
- Responses apply secret, credential, personal-data, internal-address, and platform-only-field redaction.
Durable operations
Section titled “Durable operations”Long-running tools return a durable record containing an operation_id, state,
correlation identifiers, and status semantics.
- Use
get_operationto read progress, result, or structured failure. - Call
get_operationon the server that accepted the operation. Diagnostics analysis operations remain on Diagnostics; Control operations remain on Control. - Use
cancel_operationonly when the returned operation supports cancellation. - MCP disconnection doesn’t cancel or lose the operation.
- Retrying the same mutation uses the same idempotency key.
Errors
Section titled “Errors”Tool execution errors include:
| Field | Meaning |
|---|---|
| Stable code | Machine-readable failure class |
| Operation | Canonical operation that failed |
| Impact | What did or didn’t change |
| Suggested action | Customer recovery step |
| Retryability | Whether retrying is safe |
| Request or trace ID | Support and telemetry correlation |
retry_after_seconds | Required delay when present |
Authentication failures use the HTTP/OAuth boundary. A tool execution failure doesn’t terminate the MCP session.
Transport behavior
Section titled “Transport behavior”- HTTPS only, with strict Origin validation before session creation.
- OAuth protected-resource metadata and resource indicators bind tokens to the exact server.
- Requests are stateless; the protocol doesn’t use
Mcp-Session-Id. - A broken request stream is retried as a new request rather than resumed with
Last-Event-ID. - Request cancellation propagates to API requests and to underlying operations only when those operations support cancellation.
Security boundaries
Section titled “Security boundaries”- The canonical API re-authorizes every call.
- Diagnostics has no mutating tools or write-capable backend credentials.
- Control calls validated API operations; it receives no direct Git, orchestration, customer-database, or cloud-provider write credential.
- Docs reads only the published customer documentation corpus and has no Team/App data path.
- No raw SQL, arbitrary PromQL, shell or process execution, unrestricted file read, arbitrary URL fetch, or direct telemetry-store credential is exposed.
- Customer-controlled logs, code, traces, and configuration are treated as data, never as instructions.
- Rate limits apply by Team, connection, App, operation, and cost class. Repeated identical calls are subject to loop protection.
- Initialization, discovery, calls, denials, results, and access lifecycle events are audit logged with the connection ID, principal, Team, App when applicable, operation, and correlation identifiers.