# gram install

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

## Supported agents

The `install` command supports the following AI agents:

- **Claude Code:** Using native HTTP transport with a `.mcp.json` configuration
- **Claude Desktop:** Using `.dxt` file generation for one-click installation
- **Cursor:** Using a browser-based installation flow
- **Gemini CLI:** Using configuration file generation

## 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 Gram API and configures the appropriate MCP server:

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

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

### Manual configuration

If you want to use a custom MCP URL or manually configure authentication, you can 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 Gram toolset for Claude Code:

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

By default, this creates or updates 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
```

This creates or updates the `.mcp.json` file in your 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 your environment, the CLI will use its value. Otherwise, it will use the `${MY_API_KEY}` substitution syntax in the config.

### Claude Desktop

Install a Gram toolset for Claude Desktop:

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

This generates a `.dxt` file in your `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 Gram toolset for Cursor:

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

This opens your browser with a URL that Cursor can use to install the MCP server.

### Gemini CLI

Install a Gram toolset for Gemini CLI:

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

This creates or updates the Gemini CLI configuration file with your Gram toolset.

## Common options

All install commands support the following options:

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

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

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

**Note:** You must 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 when you want to specify a custom URL or configure a non-Gram 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 your 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.

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

Gram 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 your 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 (`~/.claude/settings.local.json`). Configuration is available across all projects for the current user.
- **`project`:** Installs to the project-level configuration (`.mcp.json` in the current directory). 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 when you want the same MCP servers available in all your projects
- Use the `project` scope when specific MCP servers should be shared with your 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 Gram API
# 2. Derive MCP URL, headers, and env vars automatically
# 3. Create .mcp.json 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`, you can specify a different project:

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

### Using different profiles

You can switch between different Gram profiles as follows:

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

## Troubleshooting

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

You need to 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 you want automatic or manual configuration.

### "Failed to fetch toolset"

- Verify the toolset slug is correct
- Check that you have access to the project
- Ensure your 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 `.dxt` file again.
- **For Cursor:** Check that the browser URL was opened successfully.
- Verify that the MCP server URL is accessible.

## Related commands

- [`gram status`](/docs/mcp/reference/command-line/status): View your current Gram configuration.
- [`gram auth`](/docs/mcp/reference/command-line/auth): Authenticate with Gram.
- [`gram whoami`](/docs/mcp/reference/command-line/whoami): View your current user information.