What is the Platform MCP Server?

The TelemetryOS Platform MCP Server lets AI agents and automation tools take real actions in your TelemetryOS account — scheduling content, updating devices, pulling logs, managing playlists — through a standards-based Model Context Protocol endpoint.

It is distinct from the Documentation MCP Server. The two are complementary:

Use the Documentation MCP to ground an AI assistant's answers in the docs. Use the Platform MCP when you want the assistant to actually change something in your TelemetryOS account.

🔐

The Platform MCP Server gives agents the ability to modify your account. Grant the narrowest permissions that still let the agent do its job, and set an expiry date.

How Permissions Work

Every request to the Platform MCP is authenticated with an MCP token and authorized against that token's permission set. Permissions are expressed as dot-notation strings and enforced by the gateway before any backend service is called.

Resources and Actions

Permissions combine a resource and an action:

Each resource supports four actions: read, create, update, and delete.

Resources that aren't part of your account's plan cannot be added to a token — they're rejected at token creation.

Field Restrictions

For read, create, and update, you can optionally restrict a permission to specific fields on the resource. delete is always action-level — there are no partial deletes.

How restrictions are enforced:

• On read, the response payload is filtered to the permitted fields before it's returned. Identifier fields (id, _id) are always included.
• On create and update, non-permitted fields in the request are rejected.
• Field filtering is applied at the top level of the response. Nested objects pass through unfiltered.

Precedence rule: broader always wins. If a token has both devices.update and devices.update.name, the broader devices.update takes effect — the agent can update any field. The same applies to read.

⚠️

Field-restricted create can conflict with server-required fields. If your token only permits media.create.title but the server also requires a url, the request will fail validation. Confirm your field list covers every required field for the resource before issuing the token.

Example Scopes

Three common agent profiles and the permissions they need:

Creating a Token

MCP tokens are created by account admins in Studio under Account Settings → MCP Tokens.

1. Name the token. Use a name that identifies the integration (e.g., "Playlist Scheduler — Claude Code").
2. Build permissions using the matrix. Rows are resources, columns are read, create, update, delete. Check the cells the agent needs. For read, create, and update, you can optionally expand the cell to restrict it to specific fields. Plan-gated resources appear as disabled rows.
3. Set an expiry (recommended). Short-lived tokens reduce blast radius if leaked.
4. Create the token.

On creation, Studio shows the plaintext token once. Copy it immediately — it is never stored and cannot be retrieved again. If you lose it, revoke the token and create a new one.

The creation success screen also shows ready-to-paste config snippets for Codex and Claude Code.

Connecting a Client

Set the token as an environment variable so it never ends up in a config file or repository:

export TELEMETRYOS_MCP_TOKEN="m..."

{
  "mcpServers": {
    "telemetryos": {
      "type": "http",
      "url": "https://mcp.telemetryos.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TELEMETRYOS_MCP_TOKEN}"
      }
    }
  }
}

Once connected, the client will discover the MCP tools your token permits. A read-only monitoring token will see only the read tools; an update-capable token will also see update tools. Tools the token doesn't permit are not advertised.

Quotas and Rate Limits

Platform MCP calls count against your account's API usage quota, the same way direct API calls do. Each token also has its own rate limit.

Every metered response includes these headers:

• API-Rate-Limit — the token's per-window limit
• API-Rate-Limit-Remaining — calls remaining in the current window
• API-Rate-Limit-Reset — seconds until the window resets

When a token is rate-limited, the server returns 429 Too Many Requests with a Retry-After header. When the account's API quota is exhausted, further calls are rejected until usage flushes.

Revoking a Token

Any admin can revoke a token from the token list in Studio. Revocation is immediate — the next request made with that token is rejected. Revocation is permanent; a revoked token cannot be re-enabled.

Tokens with an expiry date are automatically rejected after their expiry time passes.

Security Best Practices

• One token per integration. Don't share tokens across agents or environments. If you need to revoke access for one, you shouldn't have to disrupt another.
• Grant the narrowest permissions that work. Start with read only. Add update or create only when the agent demonstrably needs it. Avoid delete unless it's the whole point of the integration.
• Use field restrictions for high-privilege actions. A token that can only update playlist_id is dramatically safer than one that can update any device field.
• Set short expiries. 30–90 days is a reasonable default for most integrations. Rotate tokens rather than keeping them alive indefinitely.
• Never commit tokens. Use environment variables and secret managers.
• Revoke on suspicion. If you're unsure whether a token has been exposed, revoke it and issue a new one. The cost is seconds; the alternative can be a security incident.

Troubleshooting