Model Context Protocol (MCP)

The SmallPict MCP Server (@smallpict/mcp) implements the open Model Context Protocol standard, giving Large Language Models (LLMs) and autonomous AI coding agents native tools to inspect, compress, convert, and manage web assets directly within their workflow.

Overview

• Supported clients: Works with Claude for Desktop, Cursor, Google Antigravity (AGY), OpenCode, Windsurf, Cline / Roo Code, Goose, and any MCP-compliant runtime.
• No build step: Runs with npx -y @smallpict/mcp on Node.js 18+.
• stdio transport: Communicates over standard input/output. Logs go to stderr so they never corrupt the JSON-RPC stream.
• Production and sandbox: Accepts production keys (sp_live_...) and sandbox keys (sp_test_...), which do not use quota.

Tools

Once the server is configured, your agent can use three tools:

1. smallpict_optimize_image

Compresses local image files or remote URLs and converts them to WebP or AVIF.

2. smallpict_get_quota

Returns your plan, monthly limit, and remaining quota.

3. smallpict_purge_cdn_cache

Purges cached images from the CDN after you update them.

Setup

1. Claude for Desktop

Add the smallpict server definition to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{  "mcpServers": {    "smallpict": {      "command": "npx",      "args": [        "-y",        "@smallpict/mcp"      ],      "env": {        "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY"      }    }  }}

Restart Claude Desktop. The SmallPict tools then appear in the tools menu.

2. Cursor IDE

Configure SmallPict MCP in Cursor globally or per-project:

Option A: Cursor Global Settings

1. Open Cursor Settings (Cmd + , or Ctrl + ,).
2. Navigate to Features → MCP Servers.
3. Click + Add New MCP Server.
   • Name: smallpict
   • Type: command
   • Command: npx -y @smallpict/mcp
   • Environment Variables: SMALLPICT_API_KEY=sp_live_YOUR_API_KEY

Option B: Workspace Configuration (.cursor/mcp.json)

Create a file at .cursor/mcp.json in your project root:

{  "mcpServers": {    "smallpict": {      "command": "npx",      "args": [        "-y",        "@smallpict/mcp"      ],      "env": {        "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY"      }    }  }}

3. Google Antigravity (AGY)

For developers using the Antigravity multi-agent coding environment, add the SmallPict MCP server to ~/.gemini/antigravity/mcp/smallpict/mcp.json or your workspace settings:

{  "mcpServers": {    "smallpict": {      "command": "npx",      "args": [        "-y",        "@smallpict/mcp"      ],      "env": {        "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY"      }    }  }}

Antigravity agents can then optimize project images as part of their tasks.

4. VS Code (Cline / Roo Code)

In VS Code with the Cline or Roo Code extension:

1. Open the Cline panel and click the MCP Servers icon.
2. Select Configure MCP Servers (opens cline_mcp_settings.json).
3. Add the server entry:

{  "mcpServers": {    "smallpict": {      "command": "npx",      "args": [        "-y",        "@smallpict/mcp"      ],      "env": {        "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY"      },      "disabled": false,      "autoApprove": [        "smallpict_get_quota",        "smallpict_optimize_image"      ]    }  }}

5. Windsurf (Codeium)

Edit your Windsurf configuration at ~/.codeium/windsurf/mcp_config.json:

{  "mcpServers": {    "smallpict": {      "command": "npx",      "args": [        "-y",        "@smallpict/mcp"      ],      "env": {        "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY"      }    }  }}

6. OpenCode, Codex & Custom AI Runners

For terminal-based agents (Goose, OpenCode, custom LangChain / LlamaIndex scripts), invoke @smallpict/mcp directly via standard input/output:

# Launch directly in your agent subprocessSMALLPICT_API_KEY"sp_live_YOUR_KEY" npx -y @smallpict/mcp

Example prompts

Once configured, you can ask your agent in plain language:

Optimize local images

"Agent, find all PNG and JPEG images inside public/images/, convert them to WebP at quality 80, and give me a summary table of how many bytes we saved."

Check quota

"What is my remaining SmallPict quota this month before I start bulk optimizing hero assets?"

Purge the CDN cache

"I just replaced hero-banner.jpg on my site. Please purge the SmallPict CDN cache for that asset."

Testing with sandbox keys

You can test without consuming your monthly transformation quota by using a Sandbox key:

"env": {  "SMALLPICT_API_KEY": "sp_test_sandbox_secret_key"}

• Images are processed by the same pipeline as production.
• Requests are tracked separately and do not use your monthly quota.
• Converted files are deleted after 24 hours.