Skip to main content
The mcp command group manages Model Context Protocol (MCP) servers, which extend Forge’s capabilities by providing additional tools, resources, and integrations.

​
Usage

forge mcp [SUBCOMMAND] [OPTIONS]

​
Subcommands

​
import

Import server configuration from JSON. 
forge mcp import <JSON> [OPTIONS]
​
json
string
required
JSON configuration to import.
forge mcp import '{"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"]}'
​
--scope
enum
default:"local"
Configuration scope. Available scopes:
  • local - Project-specific configuration
  • user - Global user configuration
Alias: -s
forge mcp import '{...}' --scope user
forge mcp import '{...}' -s local

​
list

List configured MCP servers. 
forge mcp list
​
--porcelain
boolean
default:"false"
Output in machine-readable format.
forge mcp list --porcelain

​
remove

Remove a configured server. 
forge mcp remove <NAME> [OPTIONS]
​
name
string
required
Name of the server to remove.
forge mcp remove filesystem
forge mcp remove github
​
--scope
enum
default:"local"
Configuration scope.
  • local - Project-specific configuration
  • user - Global user configuration
Alias: -s
forge mcp remove filesystem --scope user
forge mcp remove github -s local

​
show

Show server configuration details. 
forge mcp show <NAME>
​
name
string
required
Name of the server to show details for.
forge mcp show filesystem
forge mcp show github

​
reload

Reload servers and rebuild caches. 
forge mcp reload

​
Examples

​
Import Filesystem Server

forge mcp import '{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
  "env": {}
}' --scope user
Example output: 
✓ MCP server imported
  Name: filesystem
  Scope: user

​
Import GitHub Server

forge mcp import '{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_TOKEN": "ghp_..."
  }
}' --scope local

​
List MCP Servers

forge mcp list
Example output: 
Configured MCP Servers:

Name          Scope   Status    Command
filesystem    user    active    npx -y @modelcontextprotocol/server-filesystem
github        local   active    npx -y @modelcontextprotocol/server-github
postgres      user    active    npx -y @modelcontextprotocol/server-postgres

​
Show Server Details

forge mcp show filesystem
Example output: 
MCP Server: filesystem

  Scope:    user
  Status:   active
  Command:  npx -y @modelcontextprotocol/server-filesystem
  Args:
    - /home/user/projects
  
  Environment:
    (none)
  
  Capabilities:
    - read_file
    - write_file
    - list_directory
    - search_files

​
Remove Server

forge mcp remove github --scope local
Example output: 
✓ MCP server removed: github

​
Reload All Servers

forge mcp reload
Example output: 
✓ MCP servers reloaded
  Active servers: 3
  Cache rebuilt: 127 tools

​
Alternative Commands

You can also use the list command: 
forge list mcp
forge list mcps

​
Configuration Scopes

​
Local Scope

Project-specific servers (stored in ./.forge/mcp-servers.json): 
forge mcp import '{...}' --scope local
Use for:
  • Project-specific tools
  • Development-only integrations
  • Servers with project-specific configuration

​
User Scope

Global user servers (stored in ~/.config/forge/mcp-servers.json): 
forge mcp import '{...}' --scope user
Use for:
  • General-purpose tools
  • Personal integrations
  • Servers used across all projects

​
Filesystem Server

Provides file system access: 
forge mcp import '{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allow"]
}'

​
GitHub Server

Integrates with GitHub: 
forge mcp import '{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_TOKEN": "your-token"
  }
}'

​
PostgreSQL Server

Provides database access: 
forge mcp import '{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-postgres"],
  "env": {
    "POSTGRES_URL": "postgresql://..."
  }
}'

​
Slack Server

Integrates with Slack: 
forge mcp import '{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-slack"],
  "env": {
    "SLACK_TOKEN": "xoxb-..."
  }
}'

​
Machine-Readable Output

forge mcp list --porcelain | jq '.servers[] | select(.scope == "user")'

​
Configuration Files

MCP servers are configured in:
  • User scope: ~/.config/forge/mcp-servers.json
  • Local scope: ./.forge/mcp-servers.json
Example configuration: 
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}
  • forge list tool <AGENT> - List tools available to an agent (includes MCP tools)
  • forge info - View active MCP servers

​
Notes

  • MCP servers extend Forge with additional capabilities
  • Servers run as separate processes and communicate via stdio or SSE
  • Use reload after manually editing configuration files
  • Local scope takes precedence over user scope
  • Environment variables in server configs support secrets
  • See Model Context Protocol documentation for creating custom servers

Build docs developers (and LLMs) love

Get started for freeTalk to us