Connect Widgetry to your agent

#The short answer

To connect Widgetry to an agent, add the remote MCP server https://widgets.gonzaloverdugo.com/mcp to it. Chat apps such as Claude and ChatGPT connect with OAuth: you add the URL as a custom connector, sign in with Google and choose the organization. Coding agents such as Claude Code, Cursor, VS Code and Codex usually send an API key that starts with wgt_ in the header Authorization: Bearer. In Claude Code that is one command:

claude mcp add --transport http widgetry https://widgets.gonzaloverdugo.com/mcp \
  --header "Authorization: Bearer $WIDGETRY_API_KEY"

Once connected, the agent gets the widgetry_* tools (read, and also build if the credential may write) and one show_<slug> tool per published widget. What those tools do, with a full example, is in Let your AI agent build MCP Apps widgets. This page is about getting connected, client by client.

#OAuth or an API key: which one to use

Both reach the same endpoint and the same tools. Each credential belongs to one organization, and the agent only sees that organization's widgets and designs.

#OAuth: sign in from the client

The client sends you to Widgetry. You sign in with Google and land on a consent page that names the client, lists your organizations and asks you to Allow or Cancel. The organization you select there is the one the token is tied to. The page also says what the client asks for:

• widgets:read: the agent can read the organization's widgets and designs, drafts included, and show the published widgets in the conversation. It cannot change anything.
• widgets:write: it can also create, edit, publish and delete widgets and designs.

Your role still applies. Write access needs an editor or owner behind the token, so a viewer gets the reading tools only. A token without widgets:write also acts as a reader, even if you are an owner. Widgetry checks on every request that you are still a member, so removing someone from the organization cuts their agent off at once.

#API key: a header the client sends

An owner creates keys in Settings, under API keys: a name (for example "Laptop agent") and a permission, Read or Read and write. The key is shown once, together with the Claude Code command above, so copy it before you click I've saved it. Widgetry keeps only its hash.

A read key gives the agent the reading tools and the show_<slug> tools. A read and write key gives it all of them. The client sends the key as Authorization: Bearer wgt_....

#Which to use when

#Claude: claude.ai and Claude Desktop

Claude adds remote MCP servers as custom connectors (Claude docs, as of October 2026):

1. Go to Customize > Connectors and click Add custom connector.
2. Enter a name, such as Widgetry, and the URL https://widgets.gonzaloverdugo.com/mcp.
3. If the dialog asks for Authentication, choose Sign in now. If it asks for the OAuth client, choose Register automatically: Widgetry supports Dynamic Client Registration, not Claude's published identity.
4. Click Add, then Connect. Claude opens Widgetry: sign in, pick the organization and click Allow.

On a Team or Enterprise plan, an Owner adds the connector in Organization settings > Connectors and each member then clicks Connect with their own account. In a chat, turn connectors on or off from the + button, under Connectors.

Widgetry's OAuth was built and tested with claude.ai and Claude Desktop. Claude renders MCP Apps on the web, on desktop and on mobile, so show_<slug> draws the widget in the chat. Connectors you add on the web or desktop also reach the mobile app.

#ChatGPT

ChatGPT connects remote MCP servers in developer mode (OpenAI docs, as of October 2026):

1. Open Settings, select Security and login and turn on Developer mode. Whether you can depends on your account and workspace policy.
2. Go to ChatGPT Plugins, select the plus button and enter a name and a description.
3. Under Connection, enter https://widgets.gonzaloverdugo.com/mcp and create the connection.

ChatGPT authenticates with OAuth 2.1 and registers itself through Client ID Metadata Documents, Dynamic Client Registration or a predefined client; it does not send static API keys (OpenAI auth docs). Widgetry publishes the standard protected resource metadata and supports Dynamic Client Registration, so the sign-in should take you to the same consent page. The flow is standard, but as of October 2026 Widgetry's OAuth has been tested with Claude, not with ChatGPT. ChatGPT renders MCP Apps, so the widgets draw in the chat.

#Claude Code

Create a key in Settings and keep it in an environment variable, then run the command from the top of this page. Claude Code stores the server in its local scope by default; add --scope user to have it in every project (Claude Code docs).

To share the setup with a team without sharing the key, put it in .mcp.json and let each person set WIDGETRY_API_KEY. Claude Code expands ${VAR} in that file:

{
  "mcpServers": {
    "widgetry": {
      "type": "http",
      "url": "https://widgets.gonzaloverdugo.com/mcp",
      "headers": { "Authorization": "Bearer ${WIDGETRY_API_KEY}" }
    }
  }
}

Claude Code does not render MCP Apps: it calls show_<slug> and reads the result as text (which clients render MCP Apps). It can still build, edit and publish widgets through the tools. Open the editorUrl or previewUrl it gives you to see them.

#Cursor

Add the server to .cursor/mcp.json in the project, or to ~/.cursor/mcp.json for every project. Cursor reads environment variables with ${env:NAME} (Cursor docs):

{
  "mcpServers": {
    "widgetry": {
      "url": "https://widgets.gonzaloverdugo.com/mcp",
      "headers": { "Authorization": "Bearer ${env:WIDGETRY_API_KEY}" }
    }
  }
}

Cursor renders MCP Apps in its agent chat since version 2.6.

#VS Code with GitHub Copilot

Put this in .vscode/mcp.json, or run MCP: Open User Configuration for every workspace. The inputs entry makes VS Code ask for the key once and store it, so the file holds no secret (VS Code docs):

{
  "servers": {
    "widgetry": {
      "type": "http",
      "url": "https://widgets.gonzaloverdugo.com/mcp",
      "headers": { "Authorization": "Bearer ${input:widgetry-key}" }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "widgetry-key",
      "description": "Widgetry API key",
      "password": true
    }
  ]
}

GitHub Copilot's chat in VS Code renders MCP Apps.

#Codex

Codex keeps MCP servers in ~/.codex/config.toml, shared by the Codex CLI, the IDE extension and the ChatGPT desktop app. bearer_token_env_var names the variable that holds the key (Codex docs):

[mcp_servers.widgetry]
url = "https://widgets.gonzaloverdugo.com/mcp"
bearer_token_env_var = "WIDGETRY_API_KEY"

Codex also supports OAuth with Dynamic Client Registration (codex mcp login widgetry), but a key is the simpler path. Treat the Codex CLI as text only: it can build widgets, not draw them.

#Any other MCP client

Look in the client's docs for "remote MCP server", "Streamable HTTP" or "custom connector". You need two things: the URL https://widgets.gonzaloverdugo.com/mcp, and either OAuth (with Dynamic Client Registration) or a header Authorization: Bearer wgt_.... Widgetry also reads the key from an x-api-key header, for clients that only let you pick that one.

#Check that it works

Ask the agent: "Call widgetry_get_organization and tell me what you see." It answers with something like this (invented data):

{
  "organization": { "slug": "harbor-analytics", "name": "Harbor Analytics" },
  "credential": { "kind": "api-key", "scopes": ["read", "write"], "canWrite": true },
  "widgets": { "total": 4, "published": 2 },
  "designs": { "builtIn": 20, "own": 1 },
  "mcpUrl": "https://widgets.gonzaloverdugo.com/mcp",
  "appUrl": "https://widgets.gonzaloverdugo.com/widgets"
}

Check three things. The organization is the one you meant. canWrite matches what you wanted: with OAuth, the credential shows "kind": "member" and your role, and a read-only token shows the role viewer. And the numbers match what you see on the web. If the client cannot connect at all, Widgetry answered 401: the key is mistyped, missing the Bearer prefix or revoked, or the OAuth sign-in did not finish. Fix the key, or remove the connector and connect again.

#What to ask once it is connected

Some prompts to start with, and what the agent does with each:

1. "Show me my published widgets." It calls widgetry_list_widgets and lists name, status and design.
2. "Which templates can I start from?" widgetry_list_starters returns the 13 types and the script libraries.
3. "Show the sprint board widget with these tasks: ..." It calls show_<slug> with your data, and a host that renders MCP Apps draws it.
4. "Create a donut chart widget for my team's spending, in my brand design, and publish it." It reads the donut chart starter, creates the widget, sets its design and sample data, and publishes it.
5. "Make the bar chart use our sales regions: North, South, East and West." It edits the data schema and sample data with widgetry_update_widget.
6. "Add a dark mode accent to our design: a lighter teal." It sets the dark tokens with widgetry_update_design. More in Create your own design.
7. "Make a design based on nordic with an orange accent called Ember." widgetry_create_design makes a design you can put on any widget.
8. "Give me the code to use the weekly metrics widget in my own MCP server." widgetry_export_widget returns the live URL and the TypeScript to link it.
9. "Unpublish the old roadmap widget." widgetry_set_published with false. Its tool disappears from the endpoint.
10. "Open the countdown widget in the editor." It gives you the editorUrl; open it while signed in.

Widgets show the data the agent passes in. If the data lives somewhere else, give it to the agent or connect the tool that has it.

#Keep it safe

• A key is a password. Keep it in an environment variable or an input prompt, never in a file you commit or in a chat.
• Use read keys where nothing needs to write. A server that only links published widgets needs a read key.
• Revoke what you do not use. In Settings, each key shows when it was last used, and Revoke stops it at once.
• Deleting asks first. The delete tools are marked destructive, and the server tells the agent to confirm with you before it deletes. A deleted widget cannot be restored.
• Members and keys stay on the web. No agent can invite people, change roles or create keys, so no key ends up in a conversation.

Not signed up yet? Sign in with Google, then follow Getting started to publish your first widget.