---
title: "Mousepad Developer Docs: MCP, API and OAuth"
description: "Connect your own agent to Mousepad with OAuth or an API key. Create apps, edit code, preview, share with your team and publish from one workspace."
url: "https://mousepad.app/docs/agents"
---

# Mousepad · Developer docs

Connect Claude, ChatGPT or your own coding agent. Build with your model, then review, share and publish in Mousepad.

This integration is prepared for release. Connection setup will be available after the update is live.

## Connect your agent

Streamable HTTP · OAuth · no adapter required

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](https://studio.mousepad.app/settings/agents), 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](https://studio.mousepad.app/signup) and verify your email. No sales call is needed. Agent keys are self-serve in [Settings → Agent access](https://studio.mousepad.app/settings/agents); OAuth connections use the same workspace permissions. Your client may require its own paid plan. See [Mousepad plans and limits](https://mousepad.app/pricing).

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](https://studio.mousepad.app/api/agent/v1/openapi.json) and [OAuth resource metadata](https://studio.mousepad.app/.well-known/oauth-protected-resource/api/agent/mcp) 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.

| Permission | What it allows |
| --- | --- |
| `apps:read` | Read app source, saved versions and previews. Required for every connection. |
| `apps:write` | Create apps and edit code. Optional; requires Editor, Publisher or Owner. |
| `apps:publish` | Publish a saved version publicly. Optional, off by default; requires Publisher or Owner. |

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:

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](https://mousepad.app/collaborate) · [Publishing and domains](https://mousepad.app/guides#publish)

## 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.

| Tool | Purpose |
| --- | --- |
| `mousepad_list_apps` | List apps in the workspace |
| `mousepad_create_app` | Create an app from the starter template |
| `mousepad_get_app` | Read the current version and publish status |
| `mousepad_list_files` | List source files |
| `mousepad_read_file` | Read a source file |
| `mousepad_write_files` | Save changes against parentVersionId |
| `mousepad_get_preview` | Get a preview URL |
| `mousepad_list_versions` | Read saved version history |
| `mousepad_publish_app` | Start publishing an exact versionId |

### HTTP API with an agent key

Read the public [Mousepad OpenAPI 3.1 document](https://studio.mousepad.app/api/agent/v1/openapi.json) 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](https://studio.mousepad.app/.well-known/oauth-protected-resource/api/agent/mcp) and [authorization-server metadata](https://studio.mousepad.app/.well-known/oauth-authorization-server). 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](https://mousepad.app/contact) with the error and the step that failed. Keep keys, authorization codes and tokens out of your message.

## Product

- [Features](https://mousepad.app/features)
- [How it works](https://mousepad.app/how-it-works)
- [Website builder](https://mousepad.app/website-builder)
- [Business apps](https://mousepad.app/business-apps)
- [Booking and scheduling](https://mousepad.app/booking-and-scheduling)
- [CRM and client portals](https://mousepad.app/crm-and-client-portals)
- [AI assistants](https://mousepad.app/ai-assistants)
- [AI SEO and growth](https://mousepad.app/ai-seo)
- [Hosting and domains](https://mousepad.app/hosting-and-domains)

## Resources

- [Documentation](https://mousepad.app/docs)
- [Blog](https://mousepad.app/blog)
- [Templates](https://mousepad.app/templates)
- [Guides](https://mousepad.app/guides)
- [Developer docs](https://mousepad.app/docs/agents)
- [Help center](https://mousepad.app/help)
- [Changelog](https://mousepad.app/changelog)
- [Referral program](https://mousepad.app/referrals)