feat: Add gram install command for MCP server configuration & support common clients

[simplesagar]

Summary

• Adds new gram install claude-code command for configuring Gram toolsets as MCP servers in Claude Code
• Supports automatic toolset lookup via --toolset flag (fetches MCP URL and auth config from API)
• Supports manual configuration via --toolset-url flag with custom headers and environment variables
• Creates/updates .mcp.json configuration file compatible with Claude Code MCP format
• Uses mcp-remote npm package for HTTP-based MCP connections

Key Features

Automatic Configuration

gram install claude-code --toolset speakeasy-admin

• Fetches toolset from Gram API
• Automatically derives MCP URL, header name, and environment variable from toolset metadata
• Uses toolset name as the MCP server name

Manual Configuration

gram install claude-code \
  --toolset-url https://chat.speakeasy.com/mcp/speakeasy-admin \
  --header-name Mcp-Speakeasy-Admin-Api-Key \
  --env-var MCP_SPEAKEASY_ADMIN_API_KEY

• Supports custom MCP URLs
• Configurable authentication headers
• Environment variable substitution for secure API key storage

Files Changed

• cli/internal/app/install.go - New install command implementation
• cli/internal/claudecode/config.go - Claude Code config file utilities
• cli/internal/api/toolsets.go - API client for fetching toolset metadata
• cli/internal/app/app.go - Register install command
• cli/internal/api/assets.go - Fix: Add missing ServeFunction endpoint

Test Plan

• Build CLI: mise build:cli
• Run linters: mise lint:cli (should pass)
• Test automatic lookup: gram install claude-code --toolset <toolset-slug>
• Test manual URL: gram install claude-code --toolset-url https://mcp.getgram.ai/org/proj/env --api-key test-key
• Test env var substitution: gram install claude-code --toolset-url <url> --env-var MY_VAR
• Verify generated .mcp.json has correct format
• Test with custom --config-path
• Verify config works in Claude Code by restarting and checking MCP servers load

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 78d2189

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
gram	Ready	Preview	Comment	Nov 7, 2025 8:26pm
gram-docs-redirect	Ready	Preview	Comment	Nov 7, 2025 8:26pm
gram-landing-redirect	Ready	Preview	Comment	Nov 7, 2025 8:26pm

[qstearns]

Couple comments but good add. I think a big missing piece here seems like we're missing sending non-authentication headers for servers that require other configuration.

This seems pretty sweet - will def be using.

[qstearns]

So I could be mistaken, but I'm almost certain you can structure your object like:

{
  "serverName": {
     "type": "http",
     "url": "..."
  }
}

and use the http transport natively

[qstearns]

This is what claude code does on its own and more and more clients (including cursor) are supporting this formulation so I think it might be worth going this route

[simplesagar]

@claude

[claude]

Claude finished @simplesagar's task —— View job

---

Analyzing @qstearns's suggestion about native HTTP transport

Tasks

• Read the relevant code files to understand the current implementation
• Analyze @qstearns's suggestion about native HTTP transport
• Clarify what action is requested

---

Current Implementation

The current code has two pathways for installing MCP servers in Claude Code:

1. Native claude CLI (preferred) - cli/internal/mcp/claude_cli.go:28-36

claude mcp add --transport http <name> <url> --header "Header:value"

2. Fallback via config file - cli/internal/mcp/config.go:32-42

{
  "mcpServers": {
    "name": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "url", "--header", "Header:value"]
    }
  }
}

@qstearns's Suggestion

The review comment suggests that the fallback path should use native HTTP transport format instead of mcp-remote:

{
  "mcpServers": {
    "serverName": {
      "type": "http",
      "url": "https://...",
      "headers": {
        "Gram-Apikey": "value"
      }
    }
  }
}

This would:

• Remove the mcp-remote npm package dependency
• Use Claude Code's native HTTP transport support
• Align with how claude CLI configures servers
• Match what Cursor and other clients support

Question for @simplesagar

You tagged me but didn't specify what you'd like me to do. Would you like me to:

1. Implement the suggested change - Update the fallback config path to use native HTTP transport format?
2. Just provide analysis - Keep this as a code review comment for discussion?
3. Something else - Please clarify what action you'd like me to take.

The change would involve modifying:

• cli/internal/mcp/config.go - Change MCPServerConfig struct and BuildMCPConfig function
• cli/internal/claudecode/config.go - Update struct to support both formats or just the new format
• cli/internal/app/install_claude_code.go - Update the config building logic

Let me know how you'd like to proceed!

[simplesagar]

Implement the suggested change

[simplesagar]

@claude Implement the suggested change

[claude]

Claude finished @simplesagar's task —— View job

---

Tasks

• Read current MCP config implementation
• Read Claude Code config implementation
• Understand current structure and dependencies
• Update config structs to support native HTTP transport format
• Update BuildMCPConfig to generate native HTTP config
• Build CLI to verify changes
• Run linter to ensure code quality
• Commit and push changes

Summary

Successfully implemented @qstearns's suggestion to use native HTTP transport instead of the mcp-remote npm package for Claude Code MCP server configuration.

Changes Made

Updated the MCP configuration to use Claude Code's built-in HTTP transport:

Before (using mcp-remote):

{
  "mcpServers": {
    "name": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "url", "--header", "Header:value"]
    }
  }
}

After (native HTTP transport):

{
  "mcpServers": {
    "name": {
      "type": "http",
      "url": "https://...",
      "headers": {
        "Header-Name": "value"
      }
    }
  }
}

Benefits

• ✓ Removes dependency on mcp-remote npm package
• ✓ Uses Claude Code's native HTTP transport support
• ✓ Aligns with how claude CLI configures servers
• ✓ Matches format supported by Cursor and other MCP clients
• ✓ Maintains backward compatibility with other clients (Claude Desktop, etc.)

Files Modified

• cli/internal/mcp/config.go - Updated MCPServerConfig struct and BuildMCPConfig function
• cli/internal/claudecode/config.go - Updated MCPServerConfig struct
• cli/internal/app/install_claude_code.go - Updated to use HTTP transport fields

Verification

• ✓ CLI builds successfully
• ✓ go vet passes with no issues
• ✓ Changes committed and pushed to PR branch

---

|

[qstearns]

Product decision but claude (and most clients) seem to error on name collision rather than updating in place. I think we should probably prefer this behavior on behalf of all gram users with bad naming hygiene

[qstearns]

Sending the header like this doesn't work for me and I'm not exactly sure as to why. I always send the header as Authorization, but I know there's a way to make another incantation work. I can just never seem to figure it out. Just wanna be absolutely sure that this works for you though

[simplesagar]

@claude

[claude]

Claude finished @simplesagar's task —— View job

---

Analysis of Header Configuration

Tasks

• Read the install_claude_code.go file to understand the header implementation
• Check related MCP configuration files
• Analyze the header sending approach
• Provide technical feedback

---

Header Configuration Analysis

The implementation at line 40 in cli/internal/app/install_claude_code.go defines the default header name as "Gram-Apikey". This is the flag definition, not the actual header sending mechanism.

How Headers Are Actually Sent

The header sending happens in two different ways depending on whether claude CLI is available:

1. Native HTTP Transport (via claude CLI) - cli/internal/mcp/claude_cli.go:

// Lines 21-26
if useEnvVar {
    headerValue = fmt.Sprintf("%s:${%s}", info.HeaderName, info.EnvVarName)
} else {
    headerValue = fmt.Sprintf("%s:%s", info.HeaderName, info.APIKey)
}

// Lines 28-36
args := []string{
    "mcp",
    "add", 
    "--transport", "http",
    info.Name,
    info.URL,
    "--header", headerValue,  // Format: "Header-Name:value"
}

2. Fallback via mcp-remote package - cli/internal/mcp/config.go:

// Lines 32-40
return MCPServerConfig{
    Command: "npx",
    Args: []string{
        "-y",
        "mcp-remote",
        info.URL,
        "--header",
        headerValue,  // Format: "Header-Name:value"
    },
    Env: envConfig,
}

Both approaches use the same format: "Header-Name:value" (with a colon separator).

Addressing @qstearns's Concern

@qstearns mentioned this approach doesn't work for them and they always use Authorization. There are two separate issues here:

1. Header format: The "Header-Name:value" format should work - both claude mcp add and mcp-remote expect this format. The colon separates the header name from the value.

2. Which header to use: The code allows any header name via the --header-name flag. If you need to use Authorization, you can:

   gram install claude-code --toolset foo --header-name Authorization

Potential Issues

The current implementation may have a problem if the MCP URL itself requires headers beyond authentication. Looking at the review comment on cli/internal/mcp/config.go:32, @qstearns noted that clients support native HTTP transport, which this PR doesn't fully utilize in the fallback case.

The fallback still uses mcp-remote (an npm package), which adds an extra dependency and layer. The native approach would configure the MCP server to use HTTP transport directly in the config file:

{
  "mcpServers": {
    "serverName": {
      "type": "http",
      "url": "https://mcp.getgram.ai/...",
      "headers": {
        "Gram-Apikey": "key-value"
      }
    }
  }
}

Recommendations

1. Current implementation should work for the --header format - both tools expect colon-separated values
2. Native HTTP transport in config would be better than mcp-remote for the fallback case (as @qstearns noted in another comment)
3. Multiple headers: If servers need non-auth headers, the current implementation only supports one header. This might need expansion.
4. Testing needed: Since @qstearns reports this doesn't work for them, there may be an environmental issue or the mcp-remote package might have requirements not being met

@qstearns - Can you share what error you're seeing when you try this? That would help diagnose whether it's the header format, the mcp-remote package, or something else.

[ryan-timothy-albert]

If this is for Gram API Keys accessing servers it should be Authorization bearer