speakeasy-api
diff --git a/‎.changeset/brown-readers-sneeze.md‎
Lines changed: 32 additions & 0 deletions b/‎.changeset/brown-readers-sneeze.md‎
Lines changed: 32 additions & 0 deletions
diff --git a/‎cli/internal/api/toolsets.go‎
Lines changed: 84 additions & 0 deletions b/‎cli/internal/api/toolsets.go‎
Lines changed: 84 additions & 0 deletions
diff --git a/‎cli/internal/app/app.go‎
Lines changed: 1 addition & 0 deletions b/‎cli/internal/app/app.go‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎cli/internal/app/install.go‎
Lines changed: 101 additions & 0 deletions b/‎cli/internal/app/install.go‎
Lines changed: 101 additions & 0 deletions
diff --git a/‎cli/internal/app/install_claude_code.go‎
Lines changed: 121 additions & 0 deletions b/‎cli/internal/app/install_claude_code.go‎
Lines changed: 121 additions & 0 deletions
@@ -0,0 +1,32 @@
+---
+"server": patch
+"cli": minor
+---
+
+feat: Add gram install command for MCP server configuration & support common clients
+
+**Automatic Configuration**
+
+```bash
+gram install claude-code --toolset speakeasy-admin
+```
+
+- Fetches toolset metadata from Gram API
+- Automatically derives MCP URL from organization, project & environment or custom MCP slug
+- Intelligently determines authentication headers and environment variables from toolset security config
+- Uses toolset name as the MCP server name
+
+**Manual Configuration**
+
+```bash
+gram install claude-code
+--mcp-url https://mcp.getgram.ai/org/project/environment
+--api-key your-api-key
+--header-name Custom-Auth-Header
+--env-var MY_API_KEY
+```
+
+- Supports custom MCP URLs for non-Gram servers
+- Configurable authentication headers
+- Environment variable substitution for secure API key storage
+- Automatic detection of locally set environment variables (uses actual value if available)
@@ -0,0 +1,84 @@
+package api
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/speakeasy-api/gram/cli/internal/secret"
+	toolsets_client "github.com/speakeasy-api/gram/server/gen/http/toolsets/client"
+	"github.com/speakeasy-api/gram/server/gen/toolsets"
+	"github.com/speakeasy-api/gram/server/gen/types"
+	goahttp "goa.design/goa/v3/http"
+)
+
+type ToolsetsClientOptions struct {
+	Scheme string
+	Host   string
+}
+
+type ToolsetsClient struct {
+	client *toolsets.Client
+}
+
+func NewToolsetsClient(options *ToolsetsClientOptions) *ToolsetsClient {
+	doer := goaSharedHTTPClient
+
+	enc := goahttp.RequestEncoder
+	dec := goahttp.ResponseDecoder
+	restoreBody := false
+
+	h := toolsets_client.NewClient(options.Scheme, options.Host, doer, enc, dec, restoreBody)
+
+	client := toolsets.NewClient(
+		h.CreateToolset(),
+		h.ListToolsets(),
+		h.UpdateToolset(),
+		h.DeleteToolset(),
+		h.GetToolset(),
+		h.CheckMCPSlugAvailability(),
+		h.CloneToolset(),
+		h.AddExternalOAuthServer(),
+		h.RemoveOAuthServer(),
+	)
+
+	return &ToolsetsClient{client: client}
+}
+
+func (c *ToolsetsClient) GetToolset(
+	ctx context.Context,
+	apiKey secret.Secret,
+	projectSlug string,
+	toolsetSlug string,
+) (*types.Toolset, error) {
+	slug := types.Slug(toolsetSlug)
+	key := apiKey.Reveal()
+	payload := &toolsets.GetToolsetPayload{
+		ApikeyToken:      &key,
+		SessionToken:     nil,
+		ProjectSlugInput: &projectSlug,
+		Slug:             slug,
+	}
+
+	result, err := c.client.GetToolset(ctx, payload)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get toolset: %w", err)
+	}
+
+	return result, nil
+}
+
+func (c *ToolsetsClient) ListToolsets(ctx context.Context, apiKey secret.Secret, projectSlug string) ([]*types.ToolsetEntry, error) {
+	key := apiKey.Reveal()
+	payload := &toolsets.ListToolsetsPayload{
+		ApikeyToken:      &key,
+		SessionToken:     nil,
+		ProjectSlugInput: &projectSlug,
+	}
+
+	result, err := c.client.ListToolsets(ctx, payload)
+	if err != nil {
+		return nil, fmt.Errorf("failed to list toolsets: %w", err)
+	}
+
+	return result.Toolsets, nil
+}
@@ -33,6 +33,7 @@ func newApp() *cli.App {
 			newStatusCommand(),
 			newWhoAmICommand(),
 			newStageCommand(),
+			newInstallCommand(),
 		},
 		Flags: []cli.Flag{
 			flags.APIKey(),
 
@@ -0,0 +1,101 @@
+package app
+
+import (
+	"fmt"
+	"net/url"
+
+	"github.com/speakeasy-api/gram/cli/internal/app/logging"
+	"github.com/speakeasy-api/gram/cli/internal/flags"
+	"github.com/speakeasy-api/gram/cli/internal/mcp"
+	"github.com/speakeasy-api/gram/cli/internal/profile"
+	"github.com/speakeasy-api/gram/cli/internal/workflow"
+	"github.com/urfave/cli/v2"
+)
+
+var installFlags = []cli.Flag{
+	flags.APIKey(),
+	flags.Project(),
+	&cli.StringFlag{
+		Name:  "toolset",
+		Usage: "The slug of the Gram toolset to install (e.g., speakeasy-admin). Will automatically look up MCP configuration.",
+	},
+	&cli.StringFlag{
+		Name:  "mcp-url",
+		Usage: "The MCP server URL (e.g., https://mcp.getgram.ai/org/project/environment). Use this for manual configuration.",
+	},
+	&cli.StringFlag{
+		Name:  "name",
+		Usage: "The name to use for this MCP server in Cursor (defaults to toolset name or derived from URL)",
+	},
+	&cli.StringFlag{
+		Name:  "header",
+		Usage: "The HTTP header name for the API key (defaults to Authorization)",
+		Value: "Authorization",
+	},
+	&cli.StringFlag{
+		Name:  "env-var",
+		Usage: "Environment variable name to use for API key substitution (e.g., MCP_API_KEY). If provided, uses ${VAR} syntax instead of hardcoding the key",
+	},
+}
+
+func newInstallCommand() *cli.Command {
+	return &cli.Command{
+		Name:  "install",
+		Usage: "Install Gram toolsets as MCP servers in various clients",
+		Subcommands: []*cli.Command{
+			newInstallClaudeCodeCommand(),
+			newInstallClaudeDesktopCommand(),
+			newInstallCursorCommand(),
+			newInstallGeminiCLICommand(),
+		},
+	}
+}
+
+func resolveToolsetInfo(c *cli.Context) (*mcp.ToolsetInfo, error) {
+	ctx := c.Context
+	logger := logging.PullLogger(ctx)
+	prof := profile.FromContext(ctx)
+
+	toolsetSlug := c.String("toolset")
+	mcpURL := c.String("mcp-url")
+
+	// Validate that either toolset or mcp-url is provided
+	if toolsetSlug == "" && mcpURL == "" {
+		return nil, fmt.Errorf("either --toolset or --mcp-url must be provided")
+	}
+	if toolsetSlug != "" && mcpURL != "" {
+		return nil, fmt.Errorf("cannot provide both --toolset and --mcp-url")
+	}
+
+	// Get API URL if needed
+	var apiURL *url.URL
+	if toolsetSlug != "" {
+		var err error
+		apiURL, err = workflow.ResolveURL(c, prof)
+		if err != nil {
+			return nil, fmt.Errorf("failed to resolve API URL: %w", err)
+		}
+	}
+
+	projectSlug := workflow.ResolveProject(c, prof)
+	apiKey := workflow.ResolveKey(c, prof)
+
+	// Resolve toolset information using shared logic
+	info, err := mcp.ResolveToolsetInfo(ctx, &mcp.ResolverOptions{
+		ProjectSlug:     projectSlug,
+		ToolsetSlug:     toolsetSlug,
+		MCPURL:          mcpURL,
+		ServerName:      c.String("name"),
+		APIKey:          apiKey,
+		HeaderName:      c.String("header"),
+		EnvVar:          c.String("env-var"),
+		APIURL:          apiURL,
+		Logger:          logger,
+		IsHeaderNameSet: c.IsSet("header"),
+		IsEnvVarSet:     c.IsSet("env-var"),
+	})
+	if err != nil {
+		return nil, fmt.Errorf("failed to resolve toolset info: %w", err)
+	}
+	return info, nil
+}
@@ -0,0 +1,121 @@
+package app
+
+import (
+	"fmt"
+	"log/slog"
+
+	"github.com/speakeasy-api/gram/cli/internal/app/logging"
+	"github.com/speakeasy-api/gram/cli/internal/claudecode"
+	"github.com/speakeasy-api/gram/cli/internal/mcp"
+	"github.com/urfave/cli/v2"
+)
+
+func newInstallClaudeCodeCommand() *cli.Command {
+	return &cli.Command{
+		Name:   "claude-code",
+		Usage:  "Install a Gram toolset as an MCP server in Claude Code",
+		Flags:  installFlags,
+		Action: doInstallClaudeCode,
+	}
+}
+
+func doInstallClaudeCode(c *cli.Context) error {
+	ctx := c.Context
+	logger := logging.PullLogger(ctx)
+
+	// Resolve toolset information using shared logic
+	info, err := resolveToolsetInfo(c)
+	if err != nil {
+		return fmt.Errorf("failed to resolve toolset info: %w", err)
+	}
+
+	useEnvVar := info.EnvVarName != ""
+	if useEnvVar {
+		logger.InfoContext(ctx, "using environment variable substitution",
+			slog.String("var", info.EnvVarName),
+			slog.String("header", info.HeaderName))
+	}
+
+	// Try to use native claude CLI with HTTP transport first
+	if mcp.IsClaudeCLIAvailable() {
+		logger.InfoContext(ctx, "using claude CLI with native HTTP transport")
+
+		if err := mcp.InstallViaClaudeCLI(info, useEnvVar); err != nil {
+			logger.WarnContext(ctx, "claude CLI installation failed, falling back to config file",
+				slog.String("error", err.Error()))
+		} else {
+			// Success with claude CLI
+			logger.InfoContext(ctx, "successfully installed via claude CLI",
+				slog.String("name", info.Name),
+				slog.String("url", info.URL))
+
+			fmt.Printf("\n✓ Successfully installed MCP server '%s' via claude CLI\n", info.Name)
+			fmt.Printf("  URL: %s\n", info.URL)
+			fmt.Printf("  Transport: HTTP (native)\n")
+
+			if useEnvVar {
+				fmt.Printf("\n⚠ Remember to set the environment variable:\n")
+				fmt.Printf("  export %s='your-api-key-value'\n", info.EnvVarName)
+			}
+
+			return nil
+		}
+	} else {
+		logger.InfoContext(ctx, "claude CLI not available, using .mcp.json config file")
+	}
+
+	// Fallback: Write to .mcp.json config file
+	locations, err := claudecode.GetConfigLocations()
+	if err != nil {
+		return fmt.Errorf("failed to get config locations: %w", err)
+	}
+	configPath := locations[0].Path
+	logger.InfoContext(ctx, "using config location",
+		slog.String("path", configPath),
+		slog.String("type", locations[0].Description))
+
+	config, err := claudecode.ReadConfig(configPath)
+	if err != nil {
+		return fmt.Errorf("failed to read config: %w", err)
+	}
+
+	if _, exists := config.MCPServers[info.Name]; exists {
+		logger.WarnContext(ctx, "server with this name already exists, will be overwritten",
+			slog.String("name", info.Name))
+	}
+
+	mcpConfig := mcp.BuildMCPConfig(info, useEnvVar)
+	serverConfig := claudecode.MCPServerConfig{
+		Command: "",
+		Args:    nil,
+		Env:     nil,
+		Type:    mcpConfig.Type,
+		URL:     mcpConfig.URL,
+		Headers: mcpConfig.Headers,
+	}
+
+	config.AddOrUpdateServer(info.Name, serverConfig)
+
+	if err := claudecode.WriteConfig(configPath, config); err != nil {
+		return fmt.Errorf("failed to write config: %w", err)
+	}
+
+	logger.InfoContext(ctx, "successfully wrote MCP config",
+		slog.String("name", info.Name),
+		slog.String("url", info.URL),
+		slog.String("config", configPath))
+
+	fmt.Printf("\n✓ Successfully installed MCP server '%s'\n", info.Name)
+	fmt.Printf("  URL: %s\n", info.URL)
+	fmt.Printf("  Config: %s\n", configPath)
+	fmt.Printf("  Method: Config file (claude CLI not detected)\n")
+
+	if useEnvVar {
+		fmt.Printf("\n⚠ Remember to set the environment variable:\n")
+		fmt.Printf("  export %s='your-api-key-value'\n", info.EnvVarName)
+	}
+
+	fmt.Printf("\nRestart Claude Code to load the new MCP server.\n")
+
+	return nil
+}