Initial commit: homelab infrastructure wiki
- Full Obsidian vault content - Host configs (ice, grizzley, ubuntu, proxmox, truenas, panda, hyte) - Media stack documentation - Traefik HA setup - Automation scripts - Bachelor party planning
This commit is contained in:
Hermes Agent
255
homelab/raw/articles/forge/reference/docs-mcp-integration.md
Normal file
255
homelab/raw/articles/forge/reference/docs-mcp-integration.md
Normal file
@@ -0,0 +1,255 @@
|
||||
---
|
||||
type: agent-doc
|
||||
agent: ForgeCode
|
||||
source: https://forgecode.dev/docs/mcp-integration/
|
||||
scraped: 2026-04-28T21:02:43.447257+00:00
|
||||
content_hash: 79ade065
|
||||
---
|
||||
# .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 configforge mcp remove playwright# Remove from user configforge 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.
|
||||
Reference in New Issue
Block a user