Skip to main content

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 list - List all configured MCP servers

Displays all currently configured MCP servers with their basic information.

Usage:

forge mcp list

This command shows:

  • Server names
  • Connection status
  • Basic configuration details
forge mcp add - Add a new MCP server interactively

Launches an interactive setup process to add a new MCP server configuration.

Usage:

forge mcp add <server_name> <command/url>
forge mcp add-json - Add a server using JSON configuration

Allows you to add an MCP server by providing a complete JSON configuration.

Usage:

forge mcp add-json <your_json_config_for_mcp>
forge mcp get - Get detailed server information

Retrieves detailed information about a specific MCP server configuration.

Usage:

forge mcp get <server_name>

This displays:

  • Command/URL used by the mcp server
forge mcp remove - Remove an MCP server

Removes an MCP server configuration from your setup.

Usage:

forge mcp remove <server_name>

This will permanently remove the server configuration.

Manual Configuration​

You can also manually create MCP configurations by creating 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 are read from two locations in the following order of precedence:

  1. Local configuration (project-specific): .mcp.json in your current project directory
  2. User configuration (user-specific): Global configuration defined in the Forge configuration directory

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

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

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 to your .mcp.json file
  2. Tools appear automatically in all your agents
  3. Start using them right away in any conversation

Example Workflow​

// Configure weather MCP server in .mcp.json
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["weather-server.js"],
      "env": {
        "WEATHER_API_KEY": "your_api_key"
      }
    }
  }
}
# Now any agent can use weather tools:
> /agent forge
> What's the weather like in San Francisco?

> /agent 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