Mousepad · Developer docs

Connect your agent

Your agent writes the application with its own model. Mousepad saves the code, supplies a preview and puts the app in your workspace so your team can keep working on it.

Claude or ChatGPT

1. Open your client’s custom connector or app settings and add the remote MCP server URL above.
2. Choose OAuth and automatic client registration (DCR), if offered. Leave manually supplied client credentials empty.
3. Follow the Mousepad sign-in screen. Check the application’s destination, choose a workspace and review the requested permissions.
4. Choose Allow connection, then return to your agent. Ask it to create an app and give you the Mousepad dashboard link.

Your client’s plan and organization settings may control access to custom connectors. Client ID Metadata Documents (CIMD) are not supported; use automatic registration.

A custom agent or API client

Open Settings → Agent access, choose a workspace and create an agent key. Copy the key once and store it in your client’s secret settings. Send it as Authorization: Bearer <agent-key> on each request. Never put it in a URL, prompt, source file or browser app.

Start free and test as a draft

Create a free Mousepad account and verify your email. No sales call is needed. Agent keys are self-serve in Settings → Agent access; OAuth connections use the same workspace permissions. Your client may require its own paid plan. See Mousepad plans and limits.

1. Use a workspace containing only synthetic test apps and data. A connection can read all Standard apps in its workspace.
2. Start with apps:read to list apps. Add apps:write to create a draft and edit its source. Leave apps:publish unselected.
3. Ask your agent to build the fictional example below, inspect its preview and keep it as a draft. Share temporary preview URLs only with intended reviewers.
4. Revoke the key or connection in Agent access when you finish testing.

This workflow uses your real Mousepad workspace and its normal limits. A separate hosted sandbox is not available. Drafts are not published sites, but previews can run application code; use synthetic data and keep production credentials out of test apps.

These docs, the Mousepad OpenAPI document and OAuth resource metadata can be read without signing in once released. Reading workspace data, creating apps and publishing require authentication and the relevant permissions.

Choose permissions

A connection belongs to one person and one workspace. Read access includes every Standard app in that workspace. Use a separate workspace when an agent should see only a particular set of apps.

Backend function files under supabase/functions cannot be edited through this integration: the studio deploys those immediately, so use the studio for backend changes. The agent cannot change billing, workspace members or secret settings. It can read source code, so keep credentials out of source files. Existing hosting, plan and publishing checks still apply.

OAuth connections expire after 90 days. Revoke your connection in Settings → Agent access. Removing a member revokes their existing connections; a role change takes effect on subsequent requests.

Build and hand over

Start with a clear request. For example, for a fictional business:

Create a website for Cedar Orchard in Mousepad. Read the starter instructions, build the pages, preview the result and give me the dashboard link. Keep it as a draft.

1. Create an app, then read its template instructions and source.
2. Save file changes against the current version. If another collaborator has edited it, read the latest version and reconcile the changes before retrying.
3. Open the preview and inspect the result. A saved version is a draft until published.
4. Share the dashboard link with your team using Mousepad’s workspace invites and roles. A link alone does not grant access.
5. When you want to go live, ask your agent to publish the exact saved version, or publish it yourself in the studio.

Creating a blank app and writing source do not use Mousepad generation credits. Your model provider’s charges and Mousepad hosting and plan limits still apply.

Working with your team · Publishing and domains

API reference

MCP uses stateless Streamable HTTP with JSON responses. Send authorization on every request. Supported protocol versions: 2025-11-25, 2025-06-18. There is no server event stream; GET and DELETE return 405.

HTTP API with an agent key

Read the public Mousepad OpenAPI 3.1 document without credentials. With an agent key, list available tools at GET /api/agent/v1/tools and call a tool at POST /api/agent/v1/tools/<tool-name>. OAuth tokens authorize the MCP endpoint; HTTP tool calls require an agent key.

curl https://studio.mousepad.app/api/agent/v1/tools/mousepad_create_app \
  -H "Authorization: Bearer $MOUSEPAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Cedar Orchard"}'

Tool arguments are in their published schemas. Publishing starts an asynchronous job: poll mousepad_get_app for the outcome. A successful request is not a deployment receipt.

OAuth reference

The issuer is https://studio.mousepad.app. The resource is the full MCP URL above; send that exact resource during authorization and token exchange. Only authorization-code flow with S256 PKCE is supported.

Discover the named permissions in scopes_supported in the public OAuth protected-resource metadata and authorization-server metadata. Request only the scopes your task needs; the list of supported scopes does not grant access.

Resource discovery

/.well-known/oauth-protected-resource/api/agent/mcp

Issuer discovery

/.well-known/oauth-authorization-server

Dynamic registration

POST /api/agent/oauth/register

Authorization

GET /api/agent/oauth/authorize

Token exchange and refresh

POST /api/agent/oauth/token

Revocation

POST /api/agent/oauth/revoke

Register exact HTTPS redirect URIs. Public clients and client_secret_basic or client_secret_post clients are supported. Token requests are form-encoded. Access tokens last at most one hour; refresh tokens rotate within the 90-day connection lifetime. Reusing a consumed refresh token revokes the connection.

Additional permissions require new consent. An OAuth call missing a scope returns HTTP 403 with WWW-Authenticate and mcp/www_authenticate metadata. Refresh cannot increase access.

Troubleshooting

The connection screen expired

Start the connection again from your agent. Requests last 10 minutes; authorization codes last 2 minutes.

401: sign-in required

The token may have expired, been revoked or lost access to its workspace. Reconnect from the client. Confirm your Mousepad email before approving access.

403: permission required

Check the granted scopes and your current workspace role. Publishing needs separate consent. Reconnect if your client does not support permission upgrades.

409: version conflict

Read the latest version and reconcile your edits. Avoid overwriting a collaborator’s changes.

429: too many requests

Wait before retrying. Respect the Retry-After header when present; avoid tight polling loops.

The agent cannot publish

Leave it as a draft and publish in Mousepad, or reconnect with publish access. Review any plan, security or deployment error in the dashboard.

Still stuck? Contact Mousepad support with the error and the step that failed. Keep keys, authorization codes and tokens out of your message.