mcp-server

# Massdriver MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for [Massdriver](https://massdriver.cloud), providing AI assistants with tools to manage your infrastructure platform — projects, environments, deployments, policies, and more.

## Installation

This server is published to the [official MCP Registry](https://registry.modelcontextprotocol.io) as **`cloud.massdriver/mcp-server`** — MCP clients with registry support can discover and install it by that name.

To install manually, pick whichever suits your setup:

**Download a release binary** — grab the archive for your platform (Linux, macOS, or Windows; amd64 and arm64) from [GitHub Releases](https://github.com/massdriver-cloud/mcp-server/releases) and put `mcp-server` on your `PATH`.

**Go install** (requires Go 1.25+):

```bash
go install github.com/massdriver-cloud/mcp-server@latest
```

**Docker**:

```bash
docker pull massdrivercloud/mcp-server
```

**Build from source**:

```bash
git clone https://github.com/massdriver-cloud/mcp-server.git
cd mcp-server
make build   # outputs ./bin/mcp-server
```

## Configuration

You'll need a Massdriver API key and your organization ID — see the [Massdriver docs](https://docs.massdriver.cloud/) for creating API credentials.

The server reads configuration from environment variables, or from a profile in `~/.config/massdriver/config.yaml`:

```bash
export MASSDRIVER_API_KEY="your-api-key"
export MASSDRIVER_ORGANIZATION_ID="your-org-id"
# Optional:
export MASSDRIVER_URL="https://api.massdriver.cloud"  # set this if you run a self-hosted Massdriver instance
export MASSDRIVER_PROFILE="default"                   # named profile in ~/.config/massdriver/config.yaml
```

### Transports

By default the server speaks MCP over **stdio** (for local tool integrations like
Claude Desktop). To serve the **Streamable HTTP** transport instead, pass `-http`
(or set `MASSDRIVER_MCP_HTTP_ADDR`):

```bash
./bin/mcp-server -http 127.0.0.1:8080
```

The HTTP endpoint is stateless and returns `application/json`, so a single tool
call is a plain POST (no session handshake required):

```bash
curl -s 127.0.0.1:8080 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_viewer","arguments":{}}}'
```

> The HTTP endpoint is unauthenticated and exposes infrastructure-mutating tools.
> Bind it to localhost or place it behind an authenticating proxy.

### Docker

The stdio transport needs an interactive stdin, so pass `-i`:

```bash
docker run --rm -i \
  -e MASSDRIVER_API_KEY \
  -e MASSDRIVER_ORGANIZATION_ID \
  massdrivercloud/mcp-server
```

On a self-hosted Massdriver instance, also pass `-e MASSDRIVER_URL`.

> **Using a profile?** `MASSDRIVER_PROFILE` reads credentials from
> `~/.config/massdriver/config.yaml`, which doesn't exist inside the container.
> Either pass the credentials as environment variables as shown above, or mount
> your config directory and point `XDG_CONFIG_HOME` at it:
>
> ```bash
> docker run --rm -i \
>   -e MASSDRIVER_PROFILE \
>   -e XDG_CONFIG_HOME=/config \
>   -v ~/.config/massdriver:/config/massdriver:ro \
>   massdrivercloud/mcp-server
> ```

## MCP Client Configuration

### Claude Code

```bash
claude mcp add massdriver \
  --env MASSDRIVER_API_KEY=your-api-key \
  --env MASSDRIVER_ORGANIZATION_ID=your-org-id \
  -- /path/to/mcp-server
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "massdriver": {
      "command": "/path/to/mcp-server",
      "env": {
        "MASSDRIVER_API_KEY": "your-api-key",
        "MASSDRIVER_ORGANIZATION_ID": "your-org-id"
      }
    }
  }
}
```

### Other Clients

The server uses stdio transport, compatible with any MCP client.

## Available Tools (94)

See [MCP_README.md](MCP_README.md) for the full tool reference, including per-tool descriptions, input conventions, pagination, and behavioral annotations.

### Projects (6)
`list_projects` `get_project` `create_project` `clone_project` `update_project` `delete_project`

### Environments (8)
`list_environments` `get_environment` `create_environment` `update_environment` `delete_environment` `set_environment_default` `remove_environment_default` `compare_environments`

### Instances (8)
`list_instances` `get_instance` `update_instance` `set_instance_secret` `remove_instance_secret` `set_remote_reference` `remove_remote_reference` `list_alarms`

### Deployments (11)
`list_deployments` `get_deployment` `get_deployment_logs` `create_deployment` `propose_deployment` `approve_deployment` `reject_deployment` `abort_deployment` `plan_deployment` `rollback_deployment` `compare_deployments`

### Components (7)
`list_components` `get_component` `add_component` `update_component` `remove_component` `link_components` `unlink_components`

### Bundles (1)
`get_bundle`

### Resources (9)
`list_resources` `get_resource` `create_resource` `update_resource` `delete_resource` `export_resource` `create_resource_grant` `delete_resource_grant` `list_resource_grants`

### Organization (4)
`get_organization` `create_custom_attribute` `update_custom_attribute` `delete_custom_attribute`

### Viewer (1)
`get_viewer`

### Audit Logs (3)
`get_audit_log` `list_audit_logs` `list_audit_log_event_types`

### Groups (10)
`list_groups` `get_group` `create_group` `update_group` `delete_group` `add_group_user` `remove_group_user` `revoke_group_invitation` `add_group_service_account` `remove_group_service_account`

### Service Accounts (5)
`list_service_accounts` `get_service_account` `create_service_account` `update_service_account` `delete_service_account`

### OCI Repos (8)
`list_oci_repos` `get_oci_repo` `create_oci_repo` `update_oci_repo` `delete_oci_repo` `create_oci_repo_grant` `delete_oci_repo_grant` `list_oci_repo_grants`

### Policies (11)
`get_policy` `create_policy` `update_policy` `delete_policy` `list_policy_actions` `list_policy_entities` `evaluate_policy` `evaluate_policies_batch` `explain_policy` `get_policy_attribute_schema` `list_policy_attribute_values`

### Server (1)
`get_server`

### URLs (1)
`get_url`

## Contributing

Development, architecture, and release documentation lives in [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[MIT](LICENSE)