speakeasy install

The speakeasy install command automates the configuration of 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 an MCP server is to pass its slug with --toolset. The CLI fetches the server configuration from the platform API and configures the MCP client:

speakeasy install claude-code --toolset <your-toolset-slug>

This command will:

Fetch the MCP server’s 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:

speakeasy install claude-code \
  --mcp-url https://ai.speakeasy.com/mcp/<server-slug> \
  --api-key your-api-key \
  --header Custom-Auth-Header

Client-specific commands

Claude Code

Install an MCP server for Claude Code:

speakeasy install claude-code --toolset speakeasy-admin

If the claude CLI is available, the server 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 server at the project level instead, use the --scope flag:

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

speakeasy 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 an MCP server for Claude Desktop:

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

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

Cursor

Install an MCP server for Cursor:

speakeasy 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 an MCP server for Gemini CLI:

speakeasy install gemini-cli --toolset speakeasy-admin

This runs gemini mcp add with native HTTP transport to register the server 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 MCP server being installed. The CLI will automatically look up the MCP configuration from the platform API.

speakeasy 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.

speakeasy install claude-code --mcp-url https://ai.speakeasy.com/mcp/<server-slug>

`—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 MCP server’s name or a name derived from the URL.

speakeasy 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 SPEAKEASY_AI_API_KEY environment variable
The API key from the current profile (~/.config/speakeasy-ai/profile.json)

speakeasy 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 MCP server’s security configuration.

speakeasy 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 MCP server’s security configuration.

speakeasy 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.

speakeasy 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 MCP servers 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
speakeasy install claude-code --toolset my-toolset

# The CLI will:
# 1. Fetch the MCP server's 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
speakeasy 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
speakeasy 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 MCP server for multiple clients
speakeasy install claude-code --toolset my-toolset
speakeasy install claude-desktop --toolset my-toolset
speakeasy install cursor --toolset my-toolset

Example 5: Project-level configuration

# Install to project-level config for team sharing
speakeasy 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:

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

speakeasy --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 server 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.

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