# gram install

The `gram install` command automates the configuration of toolsets as MCP servers across multiple AI agents. Instead of manually editing configuration files, use this command to set up MCP servers in a single step.

## Supported agents

The `install` command supports the following AI agents:

- **Claude Code:** Using the `claude` CLI with native HTTP transport, or a config file fallback
- **Claude Desktop:** Using `.mcpb` file generation for one-click installation
- **Cursor:** Using a deep link installation flow
- **Gemini CLI:** Using the `gemini` CLI with native HTTP transport

## Usage

### Basic usage (automatic configuration)

The simplest way to install a toolset is to specify the toolset slug. The CLI automatically fetches the toolset configuration from the platform API and configures the appropriate MCP server:

```bash
gram install claude-code --toolset <your-toolset-slug>
```

This command will:
- Fetch toolset metadata from the platform API
- Automatically derive the MCP URL
- Determine authentication headers and environment variables
- Create the appropriate configuration for the selected client

### Manual configuration

To use a custom MCP URL or manually configure authentication, use the `--mcp-url` flag:

```bash
gram install claude-code \
  --mcp-url https://mcp.getgram.ai/org/project/environment \
  --api-key your-api-key \
  --header Custom-Auth-Header
```

## Client-specific commands

### Claude Code

Install a toolset for Claude Code:

```bash
gram install claude-code --toolset speakeasy-admin
```

If the `claude` CLI is available, the toolset is installed by running `claude mcp add` with native HTTP transport. If the `claude` CLI isn't detected (or the installation fails), the CLI falls back to writing a configuration file directly. By default, the fallback writes to the user-level configuration file (`~/.claude/settings.local.json`). To install a toolset at the project level instead, use the `--scope` flag:

```bash
gram install claude-code --toolset speakeasy-admin --scope project
```

At the project scope, the fallback creates or updates the `.mcp.json` file in the current directory, which can be committed to version control.

**With environment variable substitution:**

```bash
gram install claude-code --toolset speakeasy-admin --env-var MY_API_KEY
```

If `MY_API_KEY` is already set in the environment, the CLI will use its value. Otherwise, it will use the `${MY_API_KEY}` substitution syntax in the config.

### Claude Desktop

Install a toolset for Claude Desktop:

```bash
gram install claude-desktop --toolset speakeasy-admin
```

This generates a `.mcpb` file in the `Downloads` folder (or a custom location specified with `--output-dir`) that can be opened to install the MCP server in Claude Desktop.

**With custom output directory:**

```bash
gram install claude-desktop --toolset speakeasy-admin --output-dir ~/Desktop
```

### Cursor

Install a toolset for Cursor:

```bash
gram install cursor --toolset speakeasy-admin
```

This opens a Cursor deep link that prompts Cursor to install the MCP server. If the link can't be opened automatically, the CLI prints the URL so it can be pasted into a browser manually.

### Gemini CLI

Install a toolset for Gemini CLI:

```bash
gram install gemini-cli --toolset speakeasy-admin
```

This runs `gemini mcp add` with native HTTP transport to register the toolset with Gemini CLI. The `gemini` command must be installed.

## Common options

All install commands support the following options:

### <code>--toolset</code>

This option adds the slug of the toolset being installed. The CLI will automatically look up the MCP configuration from the platform API.

```bash
gram install claude-code --toolset speakeasy-admin
```

**Note:** Provide either `--toolset` or `--mcp-url`, but not both.

### <code>--mcp-url</code>

This option adds the MCP server URL for manual configuration. Use it to specify a custom URL or configure a non-platform MCP server.

```bash
gram install claude-code --mcp-url https://mcp.getgram.ai/org/project/environment
```

### <code>--name</code>

This option specifies a name for the MCP server in the client configuration. If not provided, the name in the client configuration defaults to the toolset name or a name derived from the URL.

```bash
gram install claude-code --toolset speakeasy-admin --name "Speakeasy Admin Tools"
```

### <code>--api-key</code>

This option adds an API key for authentication. If not provided, the CLI will fall back to:
- The `GRAM_API_KEY` environment variable
- The API key from the current profile (`~/.gram/profile.json`)

```bash
gram install claude-code --toolset speakeasy-admin --api-key sk_1234567890
```

### <code>--header</code>

This option specifies the HTTP header name for the API key. If not specified, the header name defaults to `Authorization` or, when using `--toolset`, it is automatically derived from the toolset's security configuration.

```bash
gram install claude-code --mcp-url https://api.example.com/mcp --header X-Custom-Auth
```

### <code>--env-var</code>

This option adds an environment variable name for the API key substitution. When provided, the configuration uses `${VAR_NAME}` syntax instead of hardcoding the key. When using `--toolset`, a default environment variable name may also be derived from the toolset's security configuration.

```bash
gram install claude-code --toolset speakeasy-admin --env-var MCP_API_KEY
```

The CLI has smart environment variable handling:
- If the environment variable is already set locally, the CLI uses its actual value.
- If not set, the CLI uses the substitution syntax (for example, `${MCP_API_KEY}`).

This allows for
- **Development:** Using actual values when environment variables are set
- **Distribution:** Using substitution when sharing configs with a team

### <code>--scope</code>

This specifies the configuration scope, which determines where the MCP server configuration is installed. It defaults to `user`.

```bash
gram install claude-code --toolset speakeasy-admin --scope user
```

Available scopes:
- **`user`:** Installs the MCP server to the user-level configuration. Configuration is available across all projects for the current user.
- **`project`:** Installs to the project-level configuration (for example, `.mcp.json` in the current directory for Claude Code). The configuration can be committed to version control and shared with team members.

When to use each scope:
- Use the `user` scope for personal toolsets or to make the same MCP servers available in all projects
- Use the `project` scope when specific MCP servers should be shared with a team through version control

**Note:** This flag applies to Claude Code and Gemini CLI installations. Cursor and Claude Desktop installations use their own installation mechanisms that don't support scope selection.

## Examples

### Example 1: Quick setup with automatic configuration

```bash
# Install for Claude Code using automatic configuration
gram install claude-code --toolset my-toolset

# The CLI will:
# 1. Fetch toolset metadata from the platform API
# 2. Derive MCP URL, headers, and env vars automatically
# 3. Register the server with native HTTP transport
```

### Example 2: Environment variable substitution

```bash
# Set up with environment variable for secure key storage
export MCP_API_KEY=your-secret-key
gram install claude-code --toolset my-toolset --env-var MCP_API_KEY

# This creates a config that uses ${MCP_API_KEY}
# which can be safely shared with your team
```

### Example 3: Custom MCP URL

```bash
# Configure with a custom MCP server URL
gram install claude-code \
  --mcp-url https://custom-mcp.example.com/mcp \
  --api-key your-api-key \
  --header X-Custom-Auth \
  --name "Custom MCP Server"
```

### Example 4: Multiple clients

```bash
# Install the same toolset for multiple clients
gram install claude-code --toolset my-toolset
gram install claude-desktop --toolset my-toolset
gram install cursor --toolset my-toolset
```

### Example 5: Project-level configuration

```bash
# Install to project-level config for team sharing
gram install claude-code --toolset my-toolset --scope project

# The .mcp.json file can now be committed to version control
git add .mcp.json
git commit -m "Add MCP server configuration for team"
```

## Advanced configuration

### Custom project context

When using the automatic configuration with `--toolset`, a different project can be specified:

```bash
gram install claude-code --toolset my-toolset --project another-project
```

### Using different profiles

Switch between profiles by placing the app-level `--profile` option before the command name:

```bash
gram --profile production install claude-code --toolset my-toolset
```

## Troubleshooting

### "Either --toolset or --mcp-url must be provided"

Specify one of these options. Use `--toolset` for automatic configuration or `--mcp-url` for manual configuration.

### "Cannot provide both --toolset and --mcp-url"

These options are mutually exclusive. Choose one based on whether automatic or manual configuration is needed.

### "Failed to fetch toolset"

- Verify the toolset slug is correct
- Check access to the project
- Ensure the API key has the correct permissions

### Configuration not working in the client

- **For Claude Code:** Restart Claude Code to reload the configuration.
- **For Claude Desktop:** Try opening the `.mcpb` file again.
- **For Cursor:** Check that the deep link was opened successfully.
- Verify that the MCP server URL is accessible.

## Related commands

- [`gram status`](/docs/ai-control-plane/reference/command-line/status): Check the status of a deployment.
- [`gram auth`](/docs/ai-control-plane/reference/command-line/auth): Authenticate from the CLI.
- [`gram whoami`](/docs/ai-control-plane/reference/command-line/whoami): View the current profile information.