Model Context Protocol (MCP) Integration

The Model Context Protocol (MCP) feature allows AI agents to communicate with external tools and services, significantly extending Forge's capabilities. This implementation follows Anthropic's Model Context Protocol design, enabling seamless integration with various external systems and services.

What is MCP?

MCP provides a standardized way for AI agents to interact with external tools, APIs, and services. Through MCP, Forge can:

• Access external APIs and web services
• Integrate with specialized tools and applications
• Perform web browser automation
• Connect to databases and data sources
• Interact with custom service endpoints

MCP Configuration

Using CLI Commands

Forge provides several CLI commands to manage MCP server configurations:

forge mcp import - Import MCP servers configuration from JSON

Imports MCP server configurations from a JSON string. This command allows you to add one or multiple MCP servers at once.

Usage:

forge mcp import [OPTIONS] '<json_configuration>'

Options:

• -s, --scope <SCOPE> - Configuration scope: local (project-specific) or user (global) [default: local]
• --porcelain - Output in machine-readable format

Example - Adding multiple MCP servers to local scope:

forge mcp import '{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/sse"
    },
    "deepwiki": {
      "url": "https://mcp.deepwiki.com/sse"
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}'

Example - Adding to user (global) scope:

forge mcp import --scope user '{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}'

Output:

⏺ Added MCP server 'context7'
⏺ Added MCP server 'deepwiki'
⏺ Added MCP server 'playwright'

Scope explanation:

• local (default): Adds servers to .mcp.json in your current project directory
• user: Adds servers to your global user configuration (available across all projects)

This is the quickest way to set up multiple MCP servers at once.

forge mcp list - List all configured MCP servers

Displays all currently configured MCP servers with their basic information.

Usage:

forge mcp list

Options:

• --porcelain - Output in machine-readable format

This command shows:

• Server names
• Basic configuration details

forge mcp remove - Remove an MCP server

Removes an MCP server configuration from your setup.

Usage:

forge mcp remove [OPTIONS] <server_name>

Options:

• -s, --scope <SCOPE> - Configuration scope: local (project-specific) or user (global) [default: local]
• --porcelain - Output in machine-readable format

Examples:

# Remove from local (project) configuration
forge mcp remove playwright

# Remove from user (global) configuration
forge mcp remove --scope user playwright

This will permanently remove the server configuration from the specified scope.

forge mcp show - Show detailed server information

Shows detailed configuration for a specific MCP server.

Usage:

forge mcp show <server_name>

Options:

• --porcelain - Output in machine-readable format

This displays:

• Command/URL used by the MCP server
• Environment variables
• Arguments
• Full server configuration

forge mcp reload - Reload MCP servers

Reloads MCP servers and rebuilds caches.

Usage:

forge mcp reload

Options:

Use this command when you've made changes to your .mcp.json configuration files and want to reload the servers without restarting Forge. This is particularly useful after manually editing configuration files.

Manual Configuration

While the forge mcp import command is the quickest way to add MCP servers, you can also manually create MCP configurations by creating or editing a .mcp.json file with the following structure:

{
  "mcpServers": {
    "browser_automation": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-browser"],
      "env": {
        "BROWSER_EXECUTABLE": "/usr/bin/chromium-browser"
      }
    },
    "api_service": {
      "command": "python",
      "args": ["-m", "mcp_server", "--port", "3001"],
      "env": {
        "API_KEY": "your_api_key_here",
        "DEBUG": "true"
      }
    },
    "webhook_server": {
      "url": "http://localhost:3000/events"
    }
  }
}

Configuration Structure

Each MCP server configuration can use one of two formats:

Command-based Server

{
  "server_name": {
    "command": "command_to_execute",
    "args": ["arg1", "arg2", "arg3"],
    "env": {
      "ENV_VAR": "value",
      "ANOTHER_VAR": "another_value"
    }
  }
}

URL-based Server

{
  "server_name": {
    "url": "http://localhost:3000/events"
  }
}

Configuration Precedence

MCP configurations can exist in two scopes:

1. Local configuration (project-specific): .mcp.json in your current project directory

   • Used when you run forge mcp import (default) or forge mcp import --scope local
   • Only available to the current project

2. User configuration (global): Stored in the Forge configuration directory

   • Used when you run forge mcp import --scope user
   • Available across all projects

Note: The configuration directory is automatically determined by Forge. You can always find the exact path by running /info in the Forge Shell.

Precedence: Local configurations take precedence over user configurations, allowing you to have project-specific MCP setups while maintaining global defaults.

Disabling MCP Servers

You can temporarily disable MCP servers without removing them from your configuration by adding the "disable": true field. This is useful when you want to:

• Temporarily turn off a server without losing its configuration
• Test your setup with certain servers disabled
• Maintain server configurations for future use

Disabling a Server

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "disable": true
    },
    "weather": {
      "command": "node",
      "args": ["weather-server.js"],
      "disable": false
    }
  }
}

Behavior

• "disable": true: The server is completely ignored by Forge and won't be loaded
• "disable": false or field omitted: The server operates normally
• Disabled servers remain in your configuration file for easy re-enabling

Use Cases

{
  "mcpServers": {
    "production_api": {
      "url": "https://api.production.com/mcp/",
      "disable": true
    },
    "staging_api": {
      "url": "https://api.staging.com/mcp/",
      "disable": false
    },
    "development_tools": {
      "command": "npx",
      "args": ["@devtools/mcp"],
      "disable": false
    }
  }
}

This allows you to maintain different server configurations for different environments and easily switch between them by toggling the disable field.

How MCP Tools Work with Agents

Once you set up an MCP server, its tools automatically become available to all your agents. No extra configuration needed!

How It Works

1. Add MCP server using forge mcp import command or by editing your .mcp.json file
2. Tools appear automatically in all your agents
3. Start using them right away in any conversation

Example Workflow

Option 1: Using the import command (recommended)

forge mcp import '{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["weather-server.js"],
      "env": {
        "WEATHER_API_KEY": "your_api_key"
      }
    }
  }
}'

Option 2: Manually editing .mcp.json

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["weather-server.js"],
      "env": {
        "WEATHER_API_KEY": "your_api_key"
      }
    }
  }
}

Now any agent can use weather tools:

> /forge
> What's the weather like in San Francisco?

> /muse
> Get weather data for New York and create a summary

The get_weather tool is now available to all your agents automatically!

What You Get

• Works with every agent - Forge, Muse, custom agents, all of them
• No setup needed - Just add the MCP server and you're done
• Instant access - Tools work immediately after configuration

Example Use Cases

Web Browser Automation

Configure an MCP server for browser automation to enable Forge to interact with web pages:

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-browser"],
      "env": {
        "HEADLESS": "false",
        "VIEWPORT_WIDTH": "1920",
        "VIEWPORT_HEIGHT": "1080"
      }
    }
  }
}

Use cases:

• Automated testing of web applications
• Data scraping and extraction
• Form filling and submission
• UI interaction testing

External API Interactions

Set up MCP servers to interact with external APIs:

{
  "mcpServers": {
    "weather_api": {
      "command": "python",
      "args": ["-m", "weather_mcp_server"],
      "env": {
        "WEATHER_API_KEY": "your_api_key",
        "DEFAULT_LOCATION": "San Francisco"
      }
    }
  }
}

Use cases:

• Fetching real-time data
• Integrating with third-party services
• Accessing specialized APIs
• Data synchronization

Tool Integration

Connect specialized development tools through MCP:

{
  "mcpServers": {
    "database_tools": {
      "command": "node",
      "args": ["database-mcp-server.js"],
      "env": {
        "DB_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/db",
        "QUERY_TIMEOUT": "30000"
      }
    }
  }
}

Use cases:

• Database query execution
• Schema management
• Data migration tools
• Performance monitoring

Custom Service Connections

Create connections to custom internal services:

{
  "mcpServers": {
    "internal_api": {
      "url": "http://internal-service.company.com/mcp",
      "env": {
        "AUTH_TOKEN": "internal_service_token"
      }
    }
  }
}

Use cases:

• Internal tool integration
• Custom workflow automation
• Proprietary system access
• Enterprise service connections

Best Practices

Security Considerations

• Environment Variables: Store sensitive information like API keys in environment variables rather than in configuration files
• Access Control: Limit MCP server permissions to only what's necessary
• Network Security: Use secure connections (HTTPS) for URL-based servers
• Credential Management: Rotate API keys and tokens regularly

Troubleshooting

Common Issues

Server Connection Failures:

• Verify server URLs and ports are correct
• Check network connectivity
• Ensure required environment variables are set
• Validate authentication credentials

Command Execution Errors:

• Verify command paths and arguments
• Check file permissions
• Ensure required dependencies are installed
• Review environment variable configurations

Configuration Problems:

• Validate JSON syntax in .mcp.json files
• Check configuration file locations
• Verify servers are not disabled with "disable": true
• Use forge mcp list to see which servers are actually loaded