MCP tools

Use this reference to understand what your connected AI tool can do in Display.dev and which permissions apply. For initial setup, start with Quickstart or the guide for your AI tool.

MCP means Model Context Protocol. It is the open protocol that Cursor, Codex, Claude Code, and other agents use to call tools.

Choose a connection

Choose OAuth when the host supports it. A browser opens so you can sign in, select an organization, and approve access without copying a key.

To connect to the authenticated server, you need a Display.dev account and organization. An OAuth connection acts with your current role in the organization you select during authorization. An API-key connection acts with the scope assigned to that key. A user-owned key is also bounded by its owner's current role. An organization-scoped service key has no member role: it can work with Public and Company artifacts but cannot read or edit Private content, use member tools, or use any comment tool except list_comments. A private artifact can be read only by its creator and invited people.

Use an API key for headless setups or hosts where this guide does not document OAuth. Use local CLI when the host should reuse your dsp login session.

To publish without signing in, connect any remote HTTP MCP host to https://api.display.dev/v1/public/mcp. It exposes only publish and returns a preview URL plus a claim URL. See Publish without an account.

Authenticated endpoint

OAuth and API-key connections use:

https://api.display.dev/v1/mcp

An API-key client sends Authorization: Bearer <api-key>. OAuth clients discover the sign-in flow from the endpoint.

Artifact tools

The core workflow uses:

• publish, make_copy, list, search, read, edit, and get_metadata to create and inspect artifacts.
• create_upload to stage an HTML or Markdown file before publishing it through remote MCP.
• share and rename to change the audience or display name.
• delete to permanently remove an artifact.
• find only for compatibility with older clients; use list or search for new workflows.

Remote MCP keeps source reads bounded. The agent locates text with search and reads only the required range with read. A local dsp mcp connection also includes export for workflows that require the complete file.

Use make_copy to make an independent copy of an artifact from a retained version. Pass the source artifact's short_id; omit version, name, or visibility to use the current version, Copy of <source name>, and the source's current visibility. Pass share with a list of email addresses to invite people to the new artifact. The copy starts at version 1 without discussions. People invited to the source are not carried over.

For publish, omitted visibility is actor-sensitive: a user-scoped OAuth session or API key creates a Private artifact, while an organization-scoped service key creates a Company artifact. Pass a visibility when the intended audience differs. Private is available on every plan. On Free, Company and Private artifacts share the limit of 10 gated artifacts. A service-created artifact cannot later become Private; while signed in, call make_copy with visibility: "private" to create a private copy.

Publish a file through remote MCP

Use inline content for small HTML or Markdown generated in the conversation. Use staged publishing when the file already exists in code execution or is too large for a safe inline tool call:

1. Call create_upload with the file's basename and exact byte length.
2. Send the raw file bytes with PUT to the returned api.display.dev URL. Use every exact header in required_headers, including Authorization, Content-Type, and Content-Length.
3. Call publish with upload_id and the ordinary name, visibility, sharing, or update fields.

When updating an artifact, keep its established format. Omit format for inline content so the server uses the artifact's format; if you provide format, it must match. For staged files, use a .md or .html filename that matches the artifact. Publish a new artifact when converting between Markdown and HTML.

The upload capability expires after 15 minutes. It may appear in the initiating client's execution trace, but the agent must not repeat it or the source in its final response, shared diagnostics, generated artifact, or unrelated tool call. The code-execution environment must be able to reach api.display.dev. The same 10MB or 50MB per-artifact plan limit applies at upload creation and again when the agent publishes the staged file.

If staged publishing is unavailable, use dsp publish from an environment that can read the file, publish through the dashboard, or retry with inline content when the source is small enough.

Edit from an artifact

The Edit button in the artifact header copies a prompt with the artifact ID and instructions for reading its source, making focused changes, and checking the current version before updating it.

Paste the prompt into Cursor, Codex, Claude Code, or any other agent that can use display.dev through MCP or the CLI.

Collaboration and administration tools

The authenticated server also includes these groups. Your role and plan determine which calls succeed:

• Comments – list, add, edit, or delete comments; resolve or reopen threads; watch or unwatch an artifact.
• Members – list members, change roles, preview member removal, and remove a member. Listing and previewing require an Owner or Admin. Role changes and some offboarding actions require an Owner.
• Email domains – list, add, verify, or remove additional domains. Listing needs read access; adding, verifying, and removing require an Owner. The CLI and MCP server do not enable or disable the paid Pro add-on. A current Owner manages it in Settings → Email Domains.
• Organization logo – set or clear the logo. Uploading a logo requires a paid plan and an Owner or Admin.
• Referral program – get_referral_overview returns the link available to the current member or organization connection and the organization's earned, available, and used reward counts. Owners and Admins using a member connection can also receive the organization link. A missing link is returned as null; the agent must not guess why it is unavailable.

Connecting the server does not bypass artifact visibility, organization roles, plan limits, confirmation requirements, or version checks.

Tool access

The authenticated connector shows the same tools to every user. This stable list lets an agent learn the connector once instead of receiving a different tool set for each role. Seeing an administrative tool does not grant permission to use it. Display.dev checks your selected organization, role, plan, and artifact access when an agent calls the tool, then rejects an unauthorized operation.

Data access

The connector can access artifact content and metadata, including the email addresses invited to an artifact, comments, organization member names, email addresses, and roles, the organization's email domains and their verification or transfer status, referral links and reward counts, organization branding, and the account identity needed to authorize each call. Display.dev also processes the OAuth tokens used for the connection.

The connector does not read your agent host's conversation history or memory, including Claude conversation history and Claude memory, or arbitrary files. It receives only the content an agent sends in a tool call or staged upload. It does not read data from other services connected to your agent host.

Disconnect and troubleshoot

Revoke an OAuth grant from Connected apps. Revocation takes effect immediately. An agent cannot call the connector again until you reconnect and authorize a new grant.

For an API-key connection, delete the key under API keys to end access immediately. Rotating creates a replacement while the old key remains active for its grace period. Update the host's configuration before the old key expires.

If an agent cannot reach the server, confirm that the connector URL is https://api.display.dev/v1/mcp and that Display.dev is configured and enabled in the agent host. Reconnect and complete authorization. If the host caches its configuration or tool list, reload or restart it. See Troubleshooting for 401, local sign-in, and configuration failures.

When a tool reports a plan limit or role requirement, follow the action in the error or see Plans and limits and Members and roles. If the same error remains, contact support@display.dev.

Local anonymous mode

If dsp mcp starts without dsp login or DISPLAYDEV_API_KEY, it exposes only publish. Each publish returns a public preview URL and a single-use claim URL.