.mcp.json

MCP lets ForgeCode connect agents to external tools, APIs, and services.

What MCP gives you

With MCP, your agents can:

• Call external APIs and web services
• Use specialized tools from local or remote servers
• Automate browser workflows
• Connect to internal services and data systems

Quick start

Start with one command, confirm it loaded, then use the tools.

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

forge mcp list

CLI command reference

forge mcp import

Import one or more MCP servers from a JSON string.

Usage

forge mcp import [OPTIONS] '<json_configuration>'

Options

• -s, --scope <SCOPE>: local or user (default: local)
• --porcelain: machine-readable output

Examples

Add multiple 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"]
    }
  }
}'

Add a server to user scope:

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

Typical output:

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

forge mcp list

List configured MCP servers.

Usage

forge mcp list

Options

• --porcelain: machine-readable output

forge mcp show

Show full configuration for one server.

Usage

forge mcp show <server_name>

Options

• --porcelain: machine-readable output

Shows command or URL, arguments, environment variables, and final resolved config.

forge mcp remove

Remove one MCP server from a selected scope.

Usage

forge mcp remove [OPTIONS] <server_name>

Options

• -s, --scope <SCOPE>: local or user (default: local)
• --porcelain: machine-readable output

Examples

# Remove from local project config
forge mcp remove playwright

# Remove from user config
forge mcp remove --scope user playwright

forge mcp reload

Reload MCP servers after configuration changes.

Usage

forge mcp reload

Options

• --porcelain: machine-readable output

Use this after editing .mcp.json manually.

Manual configuration

If you prefer direct file editing, create or update .mcp.json.

{
  "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"
    }
  }
}

Server configuration types

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"
  }
}

Scope and precedence

MCP configuration can exist in two places:

1. Local scope: .mcp.json in the current project
2. User scope: global ForgeCode config directory

Local scope wins over user scope when both define the same server.

Note Find your resolved configuration path by running /info in ForgeCode Shell.

Disable a server without deleting it

Set "disable": true on a server entry.

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

Behavior:

• "disable": true: server is ignored and not loaded
• "disable": false or omitted: server loads normally

How tools become available to agents

After you add a server, tool registration is automatic.

Add MCP server -> ForgeCode loads config -> Tools are registered -> All agents can use them

You do not need per-agent setup.

To verify which MCP tools are available to your current agent, run:

:tools

Use this whenever you switch agents and want to confirm the active tool list.

Example setups

Browser automation

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

Use this for UI testing, data extraction, and scripted page interactions.

External API integration

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

Use this for real-time data access and API-backed workflows.

Development tool integration

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

Use this for database operations, schema work, and migration tooling.

Security checklist

• Store secrets in environment variables, not inline config
• Grant minimum server permissions
• Prefer HTTPS for URL-based servers
• Rotate API keys and access tokens regularly

Troubleshooting

Server connection failures

• Verify server URL and port
• Check network reachability
• Confirm required environment variables
• Validate credentials and tokens

Command execution failures

• Verify command path and arguments
• Check runtime dependencies
• Confirm file permissions
• Re-check environment variables

Configuration issues

• Validate .mcp.json syntax
• Confirm local vs user scope expectations
• Check whether the server is disabled
• Run forge mcp list to confirm loaded servers

What to do next

Add one server you need today, verify it with forge mcp list, and use it in your next agent session. That gives you the fastest path to a real MCP workflow.