# MCP

`mapbox mcp` registers a Mapbox MCP server — direct tool-calling access to Mapbox's APIs, not only guidance about them — with a coding agent. It knows two servers: `mapbox` (the Mapbox MCP server, at `https://mcp.mapbox.com/mcp`) and `mapbox-devkit` (the Mapbox DevKit MCP server, at `https://mcp-devkit.mapbox.com/mcp`). Four clients are supported: Claude Code, Codex, Visual Studio Code and Cursor. Both servers are the hosted endpoints, so there's no token, npm package or Node version to manage.

This is a different kind of install from [`mapbox agent-skills`](https://docs.mapbox.com/ja/cli/reference/agent-skills/) and [`mapbox generate-skills`](https://docs.mapbox.com/ja/cli/reference/generate-skills/), which write files this CLI fully owns. An MCP server is added to a config store that belongs to the client and may already list other servers, so this runs the client's own tooling (`claude mcp add`, `codex mcp add`, or the `--add-mcp` flag of Visual Studio Code and Cursor). It never replaces a server already registered under the same name.

-   [`mapbox mcp list`](#mapbox-mcp-list)
-   [`mapbox mcp install`](#mapbox-mcp-install)

## `mapbox mcp list`

Lists every known server for every supported client, and whether each is already registered. `client not found` means that client's CLI isn't on `PATH`; `config unreadable` means Visual Studio Code's or Cursor's own config file exists but couldn't be parsed. `-o json` spells each status in snake_case (`not_installed`, `client_not_found`, `config_unreadable`).

**Examples:**

```sh
mapbox mcp list
mapbox mcp list -o json
```

## `mapbox mcp install`

Registers servers with clients. With neither `--server` nor `--client`, it registers every known server with every detected client. With no `--client` named and no supported client found at all, it fails with `mcp_client_not_found` rather than doing nothing.

The command skips and names a client it can't reach or whose config it can't read, and the rest of the run continues. A registration that fails makes the command exit 1 once everything has been attempted. Running it again reports `already installed` for each server and rewrites nothing.

With Codex, registering a server can start a login as part of the install. If that login doesn't complete, the entry is still written, and it's reported as `installed, login incomplete` (`installed_login_incomplete` in JSON).

**Parameters:**

| Parameter | Description |
| --- | --- |
| `--server` | Server to install, repeatable. Defaults to every known server. Values: `mapbox`, `mapbox-devkit`. |
| `--client` | Client to install for, repeatable. Defaults to whichever clients are detected. Values: `claude-code`, `codex`, `vscode`, `cursor`. |
| `--global` | Register for every project rather than this one. Only Claude Code draws that distinction; Codex, Visual Studio Code and Cursor register for every project either way. |
| `--dry-run` | Report what would be installed, then exit without installing it. |

**Examples:**

```sh
mapbox mcp install
mapbox mcp install --server mapbox --client vscode
mapbox mcp install --server mapbox --global
mapbox mcp install --dry-run
```