Connect AI Agents to HipDeck with MCP

HipDeck provides a workspace-scoped Model Context Protocol (MCP) server that allows compatible AI clients to interact with your digital signage resources. Once connected, an authorized agent can inspect what is playing across your screens, work with playlist drafts, and assign content, all within the boundaries you set.

What an AI agent can do

With the HipDeck MCP server, an authorized AI agent can:

• Discover screens in a workspace
• Check screen connectivity and telemetry
• Inspect current playback
• List published playlists
• Read and edit playlist drafts
• Publish reviewed playlist content
• List schedules and sequences
• Assign playlists, schedules, or sequences to screens

The server always uses the authenticated workspace associated with the API key. Agents cannot supply an arbitrary workspace ID, which helps prevent cross-workspace access.

Server connection

• MCP endpoint — https://api.hipdeck.co/mcp
• Discovery metadata — https://api.hipdeck.co/.well-known/mcp.json

The server uses the MCP Streamable HTTP transport. MCP clients should send an authenticated JSON-RPC initialization request rather than opening the endpoint in a browser.

Authentication

Create a workspace-scoped public API key from Workspace → Developers in HipDeck, then configure the complete key as bearer authentication in your MCP client:

Authorization: Bearer hd_live_...

Never paste an API key into a normal chat message, public documentation, or an untrusted GPT. Store it in the MCP client's secure authentication or secret field.

The API key determines:

• The authenticated workspace
• The available operations
• The permitted screens, playlists, schedules, and sequences
• The API key environment and identity

Available scopes

Use only the scopes required by the intended operations:

• workspaces:read — Read authenticated workspace and API key context
• screens:read — List screens and inspect screen status or playback
• screens:write — Assign content to screens
• playlists:read — List playlists and read playlist drafts
• playlists:write — Create or update playlist drafts
• playlists:publish — Publish playlist drafts
• schedules:read — List schedules
• sequences:read — List sequences

A tool call fails when the API key does not include the scope required for that operation.

Available MCP tools

hipdeck_me

Returns the authenticated API key and workspace context, including the key ID, key name, workspace ID, environment, and scopes.

Requires workspaces:read.

list_screens

Lists screens in the authenticated workspace.

Optional inputs: limit, cursor.

Requires screens:read.

get_screen_status

Returns online status and telemetry for a specific screen.

Required input: screenId.

Requires screens:read.

get_screen_playback

Returns the current playback state and assignment for a specific screen.

Required input: screenId.

Requires screens:read.

list_playlists

Lists published playlists.

Optional inputs: limit, cursor, includeContent.

Requires playlists:read.

get_playlist_draft

Returns the editable canonical playlist draft and its current integer version.

Required input: playlistId.

Requires playlists:read.

create_playlist_draft

Creates an unpublished canonical playlist draft.

Required inputs: document, confirm. The confirm value must be true only after the intended draft has been reviewed.

Requires playlists:write.

update_playlist_draft

Replaces an existing playlist draft.

Required inputs: playlistId, document, expectedVersion, confirm. The expectedVersion must match the current playlist draft version.

Requires playlists:write.

publish_playlist

Publishes the current playlist draft. Publishing makes content externally visible.

Required inputs: playlistId, expectedVersion, confirm.

Requires playlists:publish.

assign_screen

Assigns a published playlist, schedule, or sequence to a screen.

Required inputs: screenId, assignment, confirm. Optional input: expectedVersion.

Requires screens:write.

Safety and confirmation

Every mutation requires an explicit confirm input. The AI agent should set confirm to true only after:

1. Identifying the intended workspace, screen, playlist, or assignment
2. Showing the user what will change
3. Confirming that the user approves the operation
4. Checking the latest resource state where appropriate

Publishing a playlist and assigning content to a screen are externally visible operations and should always require clear user approval.

Playlist version checks

Playlist drafts use optimistic version control. Before updating or publishing a playlist:

1. Call get_playlist_draft
2. Read the current expectedVersion
3. Present the intended change to the user
4. Call the mutation with that version
5. If a version conflict occurs, retrieve the draft again

Do not retry using the stale version. This prevents an AI agent from overwriting changes made by another user or process.

Connecting from ChatGPT

ChatGPT does not automatically discover arbitrary MCP servers from the public internet. To connect HipDeck:

1. Open ChatGPT settings and locate Apps, Connectors, or Developer mode.
2. Enable developer mode if it is available for the workspace.
3. Create a custom app or connector.
4. Enter HipDeck as the name.
5. Use https://api.hipdeck.co/mcp as the remote MCP server URL.
6. Select Streamable HTTP when prompted for the transport.
7. Configure bearer authentication using a HipDeck public API key.
8. Save the connector and enable it in a new chat.
9. Test the connection by asking the agent to call hipdeck_me or list_screens.

Availability of custom connectors and developer mode depends on the ChatGPT account, workspace configuration, plan, and administrator permissions.

Example requests

Useful read-only requests include:

• "Show me the screens in my HipDeck workspace."
• "Which screens are currently offline?"
• "What playlist is playing on the lobby display?"
• "List the published playlists."
• "Show me the current draft and version of the summer campaign playlist."

Requests that should require confirmation include:

• "Create a new playlist draft."
• "Update the lobby playlist."
• "Publish the reviewed campaign playlist."
• "Assign the campaign playlist to the reception screen."

Troubleshooting

If the MCP client cannot initialize:

• Confirm that the endpoint is https://api.hipdeck.co/mcp
• Confirm that Streamable HTTP is selected
• Verify that the bearer key is complete and has not expired or been revoked
• Confirm that the key includes workspaces:read
• Ensure that every request after initialization uses the MCP session identifier returned by the server
• Check that the API key belongs to the intended HipDeck workspace