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:

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:

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:

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:

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:

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:

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:

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

Cursor

Install a Gram toolset for Cursor:

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:

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:

`—toolset`

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

gram install claude-code --toolset speakeasy-admin

Note: You must provide either --toolset or --mcp-url, but not both.

`—mcp-url`

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.

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

`—name`

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.

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

`—api-key`

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)

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

`—header`

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.

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

`—env-var`

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.

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

`—scope`

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

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

# 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

# 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

# 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

# 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

# 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:

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

Using different profiles

You can switch between different Gram profiles as follows:

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.

gram status: View your current Gram configuration.
gram auth: Authenticate with Gram.
gram whoami: View your current user information.