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:

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:

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:

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:

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:

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:

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:

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

Cursor

Install a toolset for Cursor:

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:

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:

`—toolset`

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

gram install claude-code --toolset speakeasy-admin

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

`—mcp-url`

This option adds the MCP server URL for manual configuration. Use it to specify a custom URL or configure a non-platform 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 the 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. When using --toolset, a default environment variable name may also be derived from the toolset’s security configuration.

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

`—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. 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

# 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

# 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, a different project can be specified:

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:

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.

gram status: Check the status of a deployment.
gram auth: Authenticate from the CLI.
gram whoami: View the current profile information.