Sync open source content 🐝 (from 46becb23a35c53b13070bd37e6adad1b774e6fc2)

Author: beezythebot

docs/gram/clients/using-claude-code-with-gram-mcp-servers.mdx

@@ -55,7 +55,21 @@ gram install claude-code --toolset taskmaster
 This command automatically:
 - Fetches your toolset configuration from Gram
 - Derives the MCP URL and authentication settings
-- Creates a `.mcp.json` file with the correct configuration
+- Creates the correct configuration (by default in user-level `~/.claude/settings.local.json`)
+
+**Configuration Scopes:**
+
+You can control where the MCP server configuration is installed using the `--scope` flag:
+
+```bash
+# Install to user-level config (default) - available across all projects
+gram install claude-code --toolset taskmaster --scope user
+
+# Install to project-level config - can be shared with your team
+gram install claude-code --toolset taskmaster --scope project
+```
+
+Use `--scope project` when you want to commit the `.mcp.json` configuration to version control and share it with your team.
 
 For more details and advanced options, see the [`gram install` documentation](/docs/gram/command-line/install).
 

docs/gram/command-line/install.mdx

@@ -53,7 +53,13 @@ Install a Gram toolset for Claude Code:
 gram install claude-code --toolset speakeasy-admin
 ```
 
-This creates or updates the `.mcp.json` file in your current directory with the native HTTP transport configuration.
+By default, this creates or updates the user-level configuration file (`~/.claude/settings.local.json`). To install at the project level instead, use the `--scope` flag:
+
+```bash
+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:**
 
@@ -163,6 +169,24 @@ This allows for:
 - **Development**: Use actual values when env vars are set
 - **Distribution**: Use substitution when sharing configs with your team
 
+### `--scope`
+
+Configuration scope that determines where the MCP server configuration is installed. Defaults to `user`.
+
+```bash
+gram install claude-code --toolset speakeasy-admin --scope user
+```
+
+**Available scopes:**
+- **`user`** (default): Installs to user-level configuration (`~/.claude/settings.local.json`). Configuration is available across all projects for the current user.
+- **`project`**: Installs to project-level configuration (`.mcp.json` in current directory). Configuration can be committed to version control and shared with team members.
+
+**When to use each scope:**
+- Use `user` scope for personal toolsets or when you want the same MCP servers available in all your projects
+- Use `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
@@ -208,6 +232,17 @@ gram install claude-desktop --toolset my-toolset
 gram install cursor --toolset my-toolset
 ```
 
+### Example 5: Project-Level Configuration
+
+```bash
+# 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