Model Context Protocol

Explanation: what the Model Context Protocol is, and how MaShop's hosted MCP server lets your AI assistant drive your projects.

The Model Context Protocol (MCP) is a standard way for an AI assistant to call external tools. You point the assistant at a server, the assistant lists the tools that server offers, and from then on it can run those tools on your behalf. MaShop runs a real MCP server at mcp.mashop.app. Connect it once from Claude Desktop, Cursor, Windsurf, or VS Code, and your assistant can create projects, message the AI builder, read your code, check credits, and more without you leaving the chat.

What MCP is

MCP is a client/server protocol. Your AI assistant is the client. A tool provider runs the server. The two speak JSON-RPC 2.0 over HTTP.

The flow has three steps. First the client connects and calls initialize to learn the server's capabilities. Then it calls tools/list to get the catalog of tools, each with a name, a description, and an input schema. After that, whenever the model decides a task needs one of those tools, the client calls tools/call with the tool name and arguments, and the server runs the work and returns a result.

MaShop's server speaks protocol version 2025-03-26 and implements initialize, tools/list, tools/call, and ping. It uses the streamable HTTP transport: one JSON-RPC request in, one JSON-RPC response out. Every MaShop tool resolves synchronously, so there is no long-running stream to manage.

The MaShop MCP server is real and hosted

MaShop ships a dedicated server app under apps/mcp, deployed as its own project at mcp.mashop.app, separate from the marketing site and the workspace. The single MCP endpoint is:

POST https://mcp.mashop.app/mcp

The server ships a registry manifest. Its server.json declares the name app.mashop/mcp against the public registry schema, points the remote at https://mcp.mashop.app/mcp over the streamable-http transport, and advertises OAuth as its auth method. That manifest is what lets compatible clients discover the server by name instead of you pasting a URL by hand.

If a client sends a GET to /mcp by mistake, the server answers 405 with a readable body that tells the client to POST a JSON-RPC request with a Bearer token. That turns a silent misconfiguration into a clear error.

Why connect it

You connect the MaShop MCP server so the assistant you already work in can operate MaShop directly. You describe a change in plain language, the model picks the right MaShop tool, and the work runs against your account. No second tab, no copy-paste between the chat and the workspace.

The headline tool is send_message. It sends a chat message to MaShop's AI builder for a specific project. The builder reads that project's context (its products, categories, memory, and declared goal) and can call its own internal tools to generate or modify code, fix bugs, deploy, and more. By default send_message waits for the builder to finish and returns the final response. For a long request you set wait to false, get a message_id back immediately, and poll get_message until its status is complete. Use that path for heavy work, because a synchronous call can hit the 60-second host timeout.

Around that, the server exposes tools to create and list projects, inspect the generated code, read and write the AI's project and workspace memory, pull analytics, and check or top up credits. See Prompting the AI for how to phrase the messages you send through send_message, and Memory for what the knowledge tools read and write.

The 26 tools

The server publishes 26 tools across 8 categories. The list below is the catalog the server returns from tools/list, grouped the way the server's tool registry organizes them.

Category	Tools
Identity and workspace	get_me, list_workspaces, get_workspace
Projects	create_project, list_projects, get_project_status, deploy_project, set_project_visibility, remix_project, list_template_projects, list_library_projects
Knowledge (AI memory)	get_workspace_knowledge, set_workspace_knowledge, get_project_knowledge, set_project_knowledge
Agent interaction	send_message, get_message
Code inspection	list_files, read_file, get_diff, list_edits
Files	get_file_upload_url
Analytics	get_project_analytics, get_project_analytics_trend
Billing	get_credits, top_up_credits

One gate shows up the first time you call create_project. The project cannot be created until you have connected GitHub and Supabase to your MaShop account. When those are missing the tool returns the SERVICES_MISSING code and a message that names what to connect, with a workspace link. Connect the services once, then re-run the tool. See Connect your services.

Supported clients

MaShop documents four clients, and the protocol works with any other client that speaks MCP.

Client	What it is
Claude Desktop	Anthropic's desktop app
Cursor	The AI code editor
Windsurf	An agentic IDE
VS Code	Through its MCP extension

You connect any of them with the same configuration. Add a server entry pointing at the MaShop endpoint and declare OAuth as the auth type:

{
 "mcpServers": {
 "mashop": {
 "url": "https://mcp.mashop.app/mcp",
 "auth": { "type": "oauth" }
 }
 }
}

You can copy this exact snippet from the marketing page at mashop.app/mcp. After you save it, the client runs the sign-in flow and you grant access once.

How sign-in works

MaShop's MCP server uses OAuth 2.1. You sign in through a browser consent flow. There is no API key to paste or store.

The client discovers the endpoints automatically. The server publishes authorization-server metadata at /.well-known/oauth-authorization-server (RFC 8414) and protected-resource metadata at /.well-known/oauth-protected-resource (RFC 9728), so a strict client can find the registration, authorize, and token endpoints without manual setup. New clients register themselves through Dynamic Client Registration (RFC 7591) at /oauth/register; a redirect to http://localhost is allowed there so native desktop apps can complete a loopback flow.

The flow is PKCE-protected and accepts only the S256 challenge method; a plain challenge is rejected. The single scope the server grants is mcp:all. Tokens are short-lived: an access token lives 24 hours, a refresh token lives 30 days, and an authorization code is valid for 60 seconds. When a client presents a missing or expired token to /mcp, the server answers 401 with a WWW-Authenticate header that says error="invalid_token" and tells the client to provide an OAuth access token issued by mcp.mashop.app/oauth/token.

What runs under the hood

Two limits shape how the server behaves once you are connected.

Calls are rate-limited per user at 60 JSON-RPC requests every 60 seconds, using a sliding window so a burst at the end of one window cannot immediately fire a second full burst. When you cross the limit the server returns 429 with a Retry-After header and a body that reads Rate limit exceeded: 60 requests/min per user. Retry in Ns. The keying is per user, not per token, so adding a second client does not buy you a second budget.

Every tool call is recorded. The server writes an append-only entry to its mcp_call_log table for each call: which user, which client, which tool, whether it returned ok or error, and how long it took. The record is fire-and-forget, so logging never blocks or fails your call, but the trail is there to review what ran and when.

On privacy, the rule for MCP is the same as for the workspace: your prompts and generated code are not sent to OpenAI or Anthropic.

Where to go next

• Read Connect your services to clear the GitHub and Supabase gate before your first create_project call.
• Read Prompting the AI for how to phrase the messages you pass to send_message.
• Read Credits to understand what get_credits and top_up_credits report.
• See the full tool reference and live snippet on the MCP and API page.