Claude and MCP

Connector URL

Paste this URL into a connector. Do not add a trailing slash, a query string, or a fragment.

https://portal.dishplay.io/api/mcp

That host is the production portal.

Calls are JSON-RPC POSTs. tools/list returns the tools your sign-in can see. tools/call runs one of them.

Ask AI has to be on

Connectors use the account’s Ask AI switch. Owners and admins find it under Settings → Ask AI in the portal. If Ask AI is off, the connector is refused with AI_ORG_DISABLED.

Sign in with an API key

Owners and admins create a key under Settings → Ask AI → Connections and keys. The key is shown once and starts with dp_live_. Send it as Authorization: Bearer dp_live_….

Choose Read only or Editor when you create the key. A key cannot outrank the person who creates it. A Read only key is a viewer: the server tells the connector that writes are not available. An Editor key can call write tools, after confirmation, below.

A desktop client can point at the same URL:

{
  "mcpServers": {
    "dishplay": {
      "url": "https://portal.dishplay.io/api/mcp",
      "headers": { "Authorization": "Bearer dp_live_…" }
    }
  }
}

Sign in from Claude

Paste the connector URL into Claude (or another MCP client) and sign in with your Dishplay account when prompted. No client secret is needed.

• Issuer: https://portal.dishplay.io
• Protected resource: https://portal.dishplay.io/api/oauth/protected-resource
• Authorization: https://portal.dishplay.io/api/oauth/authorize
• Token: https://portal.dishplay.io/api/oauth/token
• Scopes: dishplay:read, dishplay:write, and offline_access when the connector needs a refresh token.

Dishplay opens a consent page. Pick the account, then Read only or Editor. Read only is a viewer grant. Editor is offered only if your portal role can edit and the connector asked for dishplay:write. Allow sends you back to the connector. An OAuth grant is never an admin or an owner, even if you are.

Access tokens last 60 minutes and start with dp_oat_. A refresh token lasts 90 days after it was last used. A viewer grant that calls a write gets HTTP 403 insufficient_scope.

Revoke a connector or a key under Settings → Ask AI → Connections and keys. Revoking a key does not revoke an OAuth grant, and revoking a grant does not revoke a key.

Same roles as the portal

tools/list returns only the actions this role can use. A customer id is never an argument. Every call stays inside the signed-in account.

Support agents are read-only, the same as viewers. Each tool takes a required action argument. The five tools are screens, playlists, content, folders, and locations.

Read actions

Available to every role, including a viewer key.

• screens: list, get, status, health, heartbeat, restore_requests
• playlists: list, get, content, schedule, item_schedule
• content: list, get
• folders: list
• locations: list, get, screens

A screen is online when it checked in within about the last 2 minutes, and offline otherwise. Lists page with limit and offset. The default page is 10. screens restore_requests lists requests to bring a deleted screen back. The default is pending. Approve or reject those on the Screens page. This server cannot approve them.

Writes need a confirmation

Editor and above can call write actions. Nothing is saved until the connector sends confirm=true, or confirm_id set to an id of that change. In the portal’s Ask AI chat, the same change waits on an approval card instead of confirm.

The account also has to allow changes: Settings → Ask AI → Can propose changes. If that is off, the tool returns WRITES_DISABLED and tells you an owner or admin can turn it on. A viewer cannot write even when the account allows changes.

• screens: assign_playlist, reload, restart, rename, set_orientation, set_location, set_timezone, set_sync_group, unassign_playlist
• playlists: create, rename, duplicate, update_item, update_item_schedule, add_item, remove_item, reorder
• content: import_url, upload_link, complete_upload, rename, move
• folders: create, rename
• locations: create, update

import_url can fetch a public image, video, or web page the caller names. The other actions stay inside the account. upload_link returns a signed upload URL that expires in 15 minutes. complete_upload adds the file after that upload finishes. Playlist create has no id yet, so it needs confirm=true.

Destructive actions

These also need Editor and the same confirmation.

• playlists delete is permanent. Screens that were assigned keep that assignment and show that the playlist was deleted.
• content delete moves the library item to trash, the same as the portal. Playlist references stay so it can be restored.
• folders delete moves the folder, its subfolders, and its items to trash. A folder does not have to be empty.
• locations delete is refused while the location still has screens. An empty location is deleted permanently.

What a connector cannot do

Billing, team management, passwords, and Wi-Fi passwords are not tools. Layout assignment and app assignment are not tools. A connector cannot pass a customer id, an API key, or its own URL path to act as another account.

If the connector is refused

• 401: the key is missing or revoked, or the token is not accepted.
• 403 AI_ORG_DISABLED: Ask AI is off for the account.
• 403 insufficient_scope: the grant is read-only and the action needs Editor.
• 429: the connector is over the rate limit, or the account hit the daily Ask AI usage cap. The cap clears the next UTC day.

Questions about a connection go to hello@dishplay.io.