# MCP server

URL: https://submitator.com/docs/mcp

> Connect Claude Code, Cursor, VS Code or another MCP client to the API, so your assistant creates client projects, previews and launches them and follows their listings.

The Submitator MCP server lets an AI assistant use the API for your agency. MCP, the Model Context Protocol, is how assistants such as Claude Code, Cursor and VS Code call outside tools.

Your assistant creates a client's project from a URL, shows the free preview and launches the project once you agree. Then it follows the listings as they go live. It calls the API with your agency key and does nothing the API does not.

It comes two ways:

- **The npm package** [`submitator-mcp`](https://www.npmjs.com/package/submitator-mcp) runs on your machine with `npx` (Node.js 20 or newer). It can also read local images and save reports to disk.
- **The remote server** at `https://mcp.submitator.com/mcp` needs no install. It reads and saves no files.

Both run the same code, open source under the MIT license on [GitHub](https://github.com/submitator/submitator-mcp). What it does for an agency, in short, is on [the MCP server page](https://submitator.com/mcp).

## Get a key

1. Create your agency at [app.submitator.com/agency/start](https://app.submitator.com/agency/start?next=/agency/developers/mcp). Test mode needs no payment.
2. In the console, open Developers, then MCP. Pick your client and create a test key: the key is shown once, together with that client's setup with the key already in it.

A `sbm_test_` key is free from the day you create your agency and runs in [test mode](https://submitator.com/docs/test-mode). A `sbm_live_` key comes with your first purchase, and each launch it starts spends one of your launches.

## Install

The package runs with `npx`, so there is nothing to install by hand. Keep the key in your user-level config, never in a file that lives in a repository.

Claude Code, in user scope:

```bash
claude mcp add --scope user submitator --env SUBMITATOR_API_KEY=sbm_test_... -- npx -y submitator-mcp
```

Cursor, in ~/.cursor/mcp.json:

```json
{
  "mcpServers": {
    "submitator": {
      "command": "npx",
      "args": ["-y", "submitator-mcp"],
      "env": { "SUBMITATOR_API_KEY": "sbm_test_..." }
    }
  }
}
```

VS Code, in .vscode/mcp.json:

```json
{
  "inputs": [
    { "type": "promptString", "id": "submitator-key", "description": "Submitator API key", "password": true }
  ],
  "servers": {
    "submitator": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "submitator-mcp"],
      "env": { "SUBMITATOR_API_KEY": "${input:submitator-key}" }
    }
  }
}
```

Claude Desktop, in claude_desktop_config.json:

```json
{
  "mcpServers": {
    "submitator": {
      "command": "npx",
      "args": ["-y", "submitator-mcp"],
      "env": {
        "SUBMITATOR_API_KEY": "sbm_test_...",
        "SUBMITATOR_FILES_DIR": "/path/to/client/images"
      }
    }
  }
}
```

- **Claude Code:** user scope keeps the key out of the project's `.mcp.json`.
- **Cursor:** `~/.cursor/mcp.json` is the user-level file.
- **VS Code** asks for the key when the server starts and keeps it out of the file.
- **Claude Desktop** starts servers in the disk root, so `SUBMITATOR_FILES_DIR` names the folder of the [local images](#local-files) you want to upload. Leave it out if you add images by URL only.
- **Devin Desktop (formerly Windsurf), Cline and other MCP clients:** add a server that runs `npx -y submitator-mcp` with `SUBMITATOR_API_KEY` in its environment, or use the remote server below.

## Remote server

A client that connects over HTTP can use the remote server instead of the package. Send your key in the `Authorization` header as `Bearer` and the key, or in an `X-API-Key` header.

Claude Code, remote server:

```bash
claude mcp add --transport http submitator https://mcp.submitator.com/mcp \
  --header "Authorization: Bearer $SUBMITATOR_API_KEY"
```

The remote server passes your key on to the API and keeps nothing between requests. It reads and saves no files, so `save_report_file` and local image paths work only with the package.

## Start in test mode

With a test key, projects and listings are test data: nothing is submitted, and test launches are not bought ones. Ask your assistant to run `whoami` first: it names the agency, the mode and the launches left. Then let your assistant create a project, preview it and launch it.

Test listings move on their own in about 15 minutes. `advance_test_listing` moves one on at once, and `set_test_launches` sets how many test launches you have. [Test mode](https://submitator.com/docs/test-mode) has the rules.

## What the tools do

| Tool | What it does |
| --- | --- |
| `whoami` | The agency and mode behind the key, its permissions, launches left and the hourly budget. |
| `list_projects`, `get_project` | Find client projects; read one in full. |
| `create_project`, `update_project`, `delete_draft` | Create a project from a URL, change its fields, delete a draft. |
| `set_logo`, `add_screenshot`, `remove_image` | Images from a public URL, or a local file with the package. |
| `preview_launch` | A free dry run of a launch or an add with the same arguments: how many directories, top and median DR, what is missing and the cost. |
| `find_directories`, `project_directories` | Search the catalog; see one project's directory choices. |
| `launch_project` | Starts submissions and spends one launch, a test launch with a test key. It refuses unless `confirm_selected` equals the count `preview_launch` shows for the same arguments. |
| `add_directories` | Reaches more directories from a launched project's free allowance, with the same check. |
| `list_listings`, `list_events` | Follow the listings and what changed since a given time. |
| `get_badge`, `verify_badge` | The badge install code for the client's site, and a check that it is there. |
| `create_report`, `get_report`, `save_report_file` | Build a PDF or XLSX report; save it to disk with the package. |
| `get_share_link`, `create_share_link`, `delete_share_link` | The client's progress page, with a live key. |
| `advance_test_listing`, `set_test_launches` | Test mode helpers, with a test key. |

Two prompts come with it: `launch_client_project` walks through a launch, and `client_progress_update` drafts a note for your client that does not name Submitator.

## Keys and safety

- Keep the key in your MCP client's user-level config on your own machine. Never put it in a file that lives in a repository.
- A read-only key fits an assistant that only checks status: projects, listings, events and existing reports. Building a report or a client page link needs a key with full permissions, and share links work with a live key only.
- Keep your client's approval prompt on for `launch_project`, `add_directories` and `update_project` instead of allowing them always: a launch spends one of your launches.
- `launch_project` and `add_directories` refuse unless `confirm_selected` equals the count `preview_launch` shows for the same arguments. With a live key, clients that support questions to their user (MCP elicitation) also ask you before a launch or an add, and the answer never passes through the model.
- The package reads the key from its environment and sends it only to `https://api.submitator.com`.
- Logins and their passwords do not pass through the MCP server. Read them in the console.
- Revoke a key in the console under Developers at any time.

## Local files

Only the package reads or writes files on your machine.

- **Images:** `set_logo` and `add_screenshot` read a `file_path` only inside `SUBMITATOR_FILES_DIR`, or inside the folder the client starts the server in when it is not set. Only real PNG, JPEG, GIF or WebP files up to 5 MB are read, and never through a symlink.
- **No folder, no files:** started in your home folder or the disk root without `SUBMITATOR_FILES_DIR`, the server reads no local files at all.
- **Reports:** `save_report_file` saves to your Downloads folder unless you name another one, and never over an existing file. A report that includes logins is not saved: download it from the console.

## Troubleshooting

| What the tool answers | What to do |
| --- | --- |
| No Submitator API key | Set `SUBMITATOR_API_KEY` for the package, or the `Authorization` header for the remote server, then restart the server. |
| Not a whole Submitator agency key | Paste the key again in full, with no quotes or spaces, then restart the server. |
| [`api_key_invalid`](https://submitator.com/docs/errors#api_key_invalid) (HTTP 401) | The key is unknown, revoked or expired. Create a new one in the console under Developers. |
| [`permission_denied`](https://submitator.com/docs/errors#permission_denied) (HTTP 403) | The key is read-only. Use a key with full permissions for anything that changes data. |
| [`rate_limited`](https://submitator.com/docs/errors#rate_limited) (HTTP 429) | The answer gives the seconds from `Retry-After`: wait that long, then ask again. The hourly budget is shared by every key of your agency in that mode ([Rate limits](https://submitator.com/docs/rate-limits)). |
| A tool is missing | Share link tools show with a live key only, the test helpers with a test key only and `save_report_file` with the package only. Restart the server in your client after you change the key. |

Every call the server makes is in the console's request log, under Developers: open a request to see its id, which starts with `mcp-`. When a tool fails, its answer ends with that request id. Quote it when you write to [support](https://submitator.com/docs/support).