MCP Agent Integration

Supercharge your AI coding assistants. Connect Spayse to generate, edit, and export professional diagrams directly inside your IDE.

What is Spayse MCP?

Spayse implements the **Model Context Protocol (MCP)**, an open standard that allows AI assistants (like Claude, Cursor, or Windsurf) to securely consume context, data, and tools. By adding the Spayse MCP server to your workspace, your AI assistant can generate, edit, and export professional diagrams without leaving your IDE.

Client Configuration

To connect Spayse MCP, configure the server block in your IDE client configuration file. Stdio transport (Local Mode) is the recommended path for all local developer workstations.

1. Cursor Setup

Open Cursor Settings, navigate to **Models > MCP**, click **Add New MCP Server**, select `command` / `stdio` as the type, and enter the following settings. Alternatively, edit the JSON configuration file directly:

Windows: `%APPDATA%\Cursor\User\globalStorage\storage.json`
macOS: `~/Library/Application Support/Cursor/User/globalStorage/storage.json`
Linux: `~/.config/Cursor/User/globalStorage/storage.json`

dsl

12345678{  "mcpServers": {    "spayse": {      "command": "npx",      "args": ["-y", "@spayse/mcp"]    }  }}

2. Windsurf Setup

Windsurf uses the identical configuration schema. Configure it in the settings UI under **MCP**, or edit the config file:

Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
macOS/Linux: `~/.codeium/windsurf/mcp_config.json`

dsl

12345678{  "mcpServers": {    "spayse": {      "command": "npx",      "args": ["-y", "@spayse/mcp"]    }  }}

3. Claude Desktop Setup

Paste the configuration block inside your Claude Desktop configuration file:

Windows: `%APPDATA%\Claude\claude_desktop_config.json`
macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

dsl

12345678{  "mcpServers": {    "spayse": {      "command": "npx",      "args": ["-y", "@spayse/mcp"]    }  }}

Cloud Sync Enabled

Every time your AI assistant creates or updates a diagram via the Spayse MCP server, the diagram is synced to your cloud account. You can open and edit it visually in the web dashboard in one click.

Authentication Modes

Interactive Login (Stdio Mode)

For interactive desktop use, run the login command once on your machine before starting your IDE:

npx @spayse/mcp login

This will launch your default web browser for account authentication via Clerk. Your credentials will be saved securely under `~/.spayse/auth.json`.

Developer API Keys (Headless Mode)

If you are deploying in a headless server, CI/CD pipeline, or scripting workspace where browser login is unavailable, you can authenticate using a developer API key:

Navigate to your Spayse web dashboard under **Settings > Developers**.
Generate a new Developer API Key (e.g. `spayse_key_...`).
Configure the MCP client with the `SPAYSE_API_KEY` environment variable:

dsl

1234567891011{  "mcpServers": {    "spayse": {      "command": "npx",      "args": ["-y", "@spayse/mcp"],      "env": {        "SPAYSE_API_KEY": "spayse_key_your_generated_token_here"      }    }  }}

Remote HTTP Server (Beta)

You can connect directly to the hosted serverless API without installing any local node packages.

Client Support Note

HTTP transport in MCP is currently in beta and depends heavily on client version support. If you experience connection drops, please use the recommended **Interactive Login (Stdio Mode)** instead.

dsl

12345678{  "mcpServers": {    "spayse": {      "type": "http",      "url": "https://spayse.app/api/mcp"    }  }}

Registered Tools

The MCP server exposes the following tools to connected LLM agents:

Attribute	Type	Default	Description
create_diagram	Tool	-	Generates a diagram from a natural-language description. Auto-syncs to the cloud and returns editor, image, and share links.
update_diagram	Tool	-	Modifies an existing diagram or layout code via instructions. Syncs changes and returns updated preview and cloud links.
get_diagram_code	Tool	-	Retrieves the raw Spayscript (.spy) source code for a specified saved diagram.
list_diagrams	Tool	-	Lists all Spayse diagrams available in the local directory or cloud account.
export_diagram	Tool	-	Exports a diagram structure to DSL, formatted DSL, or JSON representation.
delete_diagram	Tool	-	Deletes a saved diagram file locally or from the cloud account.
validate_dsl	Tool	-	Validates a block of Spayscript code, returning linting/syntax warnings and errors.

Tool Parameters: `create_diagram`

Attribute	Type	Default	Description
description	string	required	Natural-language description of the diagram architecture.
diagram_type	string	optional	Type hint: "architecture", "flow", "network", "ml", "database".
output_path	string	optional	Specific path to save the .spy file locally.

Feature Tiers & Gating

Spayse validates your subscription level dynamically on each generation request to customize tool outputs:

Feature	Free Plan	Pro Plan
Diagram Generations	5 creations / month	Unlimited
Preview Image URL	Watermarked SVG	Clean, High-Res SVG
Share Link	Private only	Direct public share URL
Visual Web Editor	Included	Included

Free tier users will receive helpful notifications inside the tool response showing remaining monthly limits and watermarking status, with direct dashboard upgrade prompts.