API and MCP

Reference: the MCP server, its OAuth connection, and its 26 tools.

MaShop exposes one programmatic interface: a Model Context Protocol (MCP) server at mcp.mashop.app. An MCP client (such as Claude Desktop, Cursor, Windsurf, or the VS Code MCP extension) connects over OAuth 2.1 and calls MaShop tools by name over JSON-RPC. The install guide lives at https://mashop.app/mcp.

This is the only machine interface. There is no public REST API, no published SDK, and no command-line tool. Every action you can drive from outside the workspace UI goes through one of the 26 MCP tools below.

There is no REST API

Do not look for a REST API, a npm package, or a mashop CLI. None ship. The transport is a single JSON-RPC 2.0 endpoint, POST https://mcp.mashop.app/mcp, and the only authentication it accepts is an OAuth 2.1 Bearer access token issued by the same host.

If you call POST /mcp without a token, you get HTTP 401 with a WWW-Authenticate: Bearer header pointing at the token endpoint. If you send a GET instead of a POST, you get HTTP 405 with the message POST a JSON-RPC 2.0 request with a Bearer access token. See https://mashop.app/mcp.

The transport

The server speaks Streamable HTTP: you POST one JSON-RPC 2.0 message and get one JSON-RPC response. There is no SSE or chunked streaming, because every tool resolves synchronously. The server advertises MCP protocol version 2025-03-26 and identifies itself as mashop-mcp version 0.2.0.

Four JSON-RPC methods are implemented: initialize (returns the protocol version, server info, and capabilities), tools/list (returns all 26 tool definitions), tools/call (runs one tool), and ping (a no-op heartbeat). JSON-RPC batches are accepted. Any other method returns error code -32601 (Method not implemented).

Every request is rate limited to 60 JSON-RPC requests per 60 seconds, keyed by user (not by token, so registering extra clients does not raise the cap). Over the limit returns HTTP 429 with a Retry-After header and the message Rate limit exceeded: 60 requests/min per user. Retry in Ns.

Connect over OAuth 2.1

MaShop authenticates clients with OAuth 2.1 and PKCE. The only PKCE method accepted is S256; plain is rejected. The flow is the standard four steps, all served from mcp.mashop.app.

1. Discover the endpoints

Clients read the metadata documents first. Both are served as live JSON.

Method	Path	Returns
GET	/.well-known/oauth-authorization-server	Authorization server metadata (RFC 8414): the authorize, token, and registration endpoints.
GET	/.well-known/oauth-protected-resource	Protected resource metadata (RFC 9728): which authorization server protects /mcp.

The discovery document advertises response_types_supported: ["code"], grant_types_supported: ["authorization_code", "refresh_token"], code_challenge_methods_supported: ["S256"], and the single scope mcp:all.

2. Register the client

Clients register dynamically (RFC 7591) by POSTing their redirect_uris to the registration endpoint.

Method	Path	Notes
POST	/oauth/register	Returns a client_id (and a client_secret pair) on HTTP 201.

redirect_uris is required and must be a non-empty array. Each URI must be HTTPS, except http://localhost, http://127.0.0.1, and http://[::1], which are allowed for native desktop loopback. A non-HTTPS, non-localhost URI returns error: "invalid_redirect_uri" with the description redirect_uris must be https URLs (or http://localhost for native clients). Registration is rate limited to 60 requests per minute per IP; over that returns error: "rate_limited".

Public clients register with token_endpoint_auth_method: "none" and rely on PKCE instead of a secret. The supported auth methods are client_secret_basic, client_secret_post, and none.

3. Authorize and consent

Method	Path	Notes
GET	/oauth/authorize	The consent screen. You must be signed in to your MaShop account.

The client redirects you here with client_id, redirect_uri, code_challenge, code_challenge_method=S256, and an optional state. You read the request and click Allow. The server checks that the redirect_uri exactly matches one of the registered URIs (no prefix matching), then redirects back with a single-use authorization code in the code query parameter. The code is valid for 60 seconds. A code_challenge_method other than S256 is rejected with Unsupported code_challenge_method (must be S256).

4. Exchange the code for tokens

Method	Path	Grant types
POST	/oauth/token	authorization_code and refresh_token

For authorization_code, send code, redirect_uri, and code_verifier. The server recomputes SHA256(code_verifier) in base64url and compares it to the stored code_challenge; a mismatch returns error: "invalid_grant" with PKCE code_verifier does not match code_challenge. A reused or expired code returns code is invalid, expired, or already used.

The token response contains an access token valid for 24 hours and a refresh token valid for 30 days, with token_type: "Bearer", expires_in: 86400, and scope: "mcp:all". Refresh tokens rotate: each refresh_token exchange consumes the old refresh token, revokes its paired access token, and issues a fresh pair. A refresh token presented twice returns refresh_token is invalid, expired, or revoked.

Calling a tool with the token

Send the access token as a Bearer header on every /mcp request. A missing or expired token returns HTTP 401.

curl -s https://mcp.mashop.app/mcp \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
 "jsonrpc": "2.0",
 "id": 1,
 "method": "tools/call",
 "params": {
 "name": "get_me",
 "arguments": {}
 }
 }'

Most MCP clients perform this whole flow for you. You point the client at https://mcp.mashop.app/mcp, sign in once on the consent screen, and the client stores and refreshes the token.

The 26 tools

Call tools/list for the live definitions, including each tool's JSON input schema. The catalog groups into eight categories. Tool names use snake_case.

Identity and workspace

Tool	What it does
get_me	Returns the authenticated user: id, email, display name, plan, and default workspace id. Run it first to confirm identity.
list_workspaces	Lists the workspaces you belong to. The model is one workspace per account plus any you joined as a collaborator.
get_workspace	Returns one workspace: name, your role, project count, and created date. Defaults to your personal workspace.

Projects

Tool	What it does
create_project	Creates a project from a natural-language prompt (minimum 10 characters) describing what you sell, to whom, and the tone. Returns the project id and workspace URL. Generation starts when you open that URL.
list_projects	Lists every project you own, with current status and live URL when deployed.
get_project_status	Returns build status, live URL, and last deploy timestamp for one project.
deploy_project	Triggers a deploy to your connected Netlify host and returns a deployment id plus the workspace URL where the build streams. Honours your deploy quota.
set_project_visibility	Sets a project to private or workspace. The public value is reserved and currently behaves like private.
remix_project	Creates a new project from an existing one's brief (name, vertical, description) and pre-fills the prompt so the AI regenerates the code on first open. It does not fork the repo or copy assets.
list_template_projects	Lists the starter templates you can pass to create_project.
list_library_projects	Parity-only. MaShop has no library concept, so this returns an empty array.

Knowledge

Persistent AI instructions injected into the builder's system prompt. Each setter caps the text at 10 KB; pass an empty string to clear.

Tool	What it does
get_workspace_knowledge	Reads the instructions applied to every project in a workspace.
set_workspace_knowledge	Saves workspace-wide instructions.
get_project_knowledge	Reads the instructions for one project. These take precedence over workspace knowledge.
set_project_knowledge	Saves per-project instructions.

Agent interaction

Tool	What it does
send_message	Sends a chat message to the AI builder for one project. With wait=true (default) it returns the final response; with wait=false it returns a message_id to poll.
get_message	Polls a message fired with wait=false. Returns status in_progress, complete, or error.

Code inspection

Tool	What it does
list_files	Lists every file in a project's GitHub repo at a ref. Repos over 100,000 entries are rejected.
read_file	Reads one file at a ref (defaults to HEAD). Files over 1 MB are rejected.
get_diff	Returns a unified diff between two refs. Per-file patches over 256 KB are truncated with a marker.
list_edits	Lists AI-editing sessions, newest first. Each entry is one conversation thread with the builder.

Files, analytics, and billing

Tool	What it does
get_file_upload_url	Returns a presigned PUT URL to upload an asset to the project's storage bucket. The URL expires in 1 hour; maximum size is 10 MB.
get_project_analytics	Visitor and pageview metrics over a date range of at most 90 days: unique visitors, pageviews, top 5 pages, referrers, and countries.
get_project_analytics_trend	A 5-minute pulse: unique sessions in the last 5 minutes with a per-minute breakdown.
get_credits	Shows your credit balance, current plan, and next renewal date.
top_up_credits	Returns a hosted checkout URL for a credit top-up between $5 and $1000. You open the URL to pay; no payment data crosses MaShop.

Error format

Tool errors come back two ways. Transport and protocol failures use JSON-RPC error codes: -32700 (parse error), -32600 (invalid request), -32601 (method or tool not found), -32603 (internal error), and -32001 (unauthorized). An unknown tool name returns Unknown tool: NAME.

Business-rule failures come back as a normal tool result with isError: true and a readable message. For example, create_project returns you must connect GitHub and Supabase to MaShop first when your account has no connected services, and deploy_project returns a quota message when the Free plan's cap of 3 deploys per 30 days is reached. See Connect your services for the GitHub and Supabase connection step.

Privacy

Your prompts and generated code are not sent to OpenAI or Anthropic. The MCP server passes your requests to the same AI builder the workspace uses.

Related

• Connect your services resolves the GitHub and Supabase gate that create_project enforces.
• Deploy to Netlify covers the host that deploy_project targets.
• Credits and Top-ups back the get_credits and top_up_credits tools.