Agentic tools MCP integration
ERPBridge implements standard Model Context Protocol (MCP). Codex CLI, OpenCode, OpenClaw, and Hermes Agent can connect without an ERPBridge-specific adapter.
Use stdio when the agent and erpbridge-server run on the same machine. Use Streamable HTTP when the server is remote, shared, containerized, or managed separately from the agent.
The canonical remote endpoint is https://erpbridge-host.example/mcp/. The trailing slash is part of the endpoint. The first request is a JSON-RPC initialize request sent to POST /mcp/, not to a separate /mcp/initialize route. HTTP sessions return Mcp-Session-Id for subsequent requests.
Prerequisites and securityโ
- Start ERPBridge and confirm GET https://erpbridge-host.example/mcp/health returns {"status":"ok"}.
- Register and activate the MCP tools that the agent should use.
- For protected HTTP deployments, create a token with the mcp scope and expose it to the agent through its environment or secret store.
- Use HTTPS for anything beyond a trusted local machine. Never commit a raw bearer token to an agent config.
ERPBridge accepts Authorization: Bearer TOKEN_VALUE on protected HTTP MCP requests. The administrator credential has implicit access. A scoped token needs the mcp scope. A token for metrics or logs alone cannot initialize MCP.
Example provisioning:
curl -X POST https://<erpbridge-host>/api/auth/tokens -H "Authorization: Bearer <admin-token>" -H "Content-Type: application/json" -d '{"name":"agent-mcp","scopes":["mcp"]}'
export ERPBRIDGE_MCP_TOKEN='<token-from-secure-provisioning>'
API_AUTH_TOKEN controls inbound HTTP authentication. ERP_PRIMARY_KEY and credentialRef values are server-side settings for outbound ERP calls. Never copy an upstream ERP credential into an agent config.
Codex CLIโ
Codex stores MCP servers in ~/.codex/config.toml or a trusted project-local .codex/config.toml. It supports stdio and Streamable HTTP.
Local stdio:
[mcp_servers.erpbridge]
command = "erpbridge-server"
args = ["--stdio"]
env_vars = ["ERP_PRIMARY_KEY"]
enabled_tools = ["list_employees", "list_departments"]
Remote Streamable HTTP:
[mcp_servers.erpbridge]
url = "https://<erpbridge-host>/mcp/"
bearer_token_env_var = "ERPBRIDGE_MCP_TOKEN"
enabled_tools = ["list_employees", "list_departments"]
bearer_token_env_var sends the environment value as a bearer token. stdio does not use inbound HTTP bearer authentication. Restart Codex after changing config.toml; codex mcp list and /mcp show connection status.
OpenCodeโ
OpenCode keys each MCP server by name directly under mcp in opencode.json or opencode.jsonc. Do not nest servers under mcp.servers; that shape fails config validation on current releases.
Local stdio:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"erpbridge": {
"type": "local",
"command": ["erpbridge-server", "--stdio"],
"enabled": true,
"environment": {
"ERP_PRIMARY_KEY": "{env:ERP_PRIMARY_KEY}"
}
}
}
}
Remote Streamable HTTP:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"erpbridge": {
"type": "remote",
"url": "https://<erpbridge-host>/mcp/",
"oauth": false,
"enabled": true,
"headers": {
"Authorization": "Bearer {env:ERPBRIDGE_MCP_TOKEN}"
}
}
}
}
Set oauth to false so OpenCode does not start an OAuth flow against the
static bearer-token endpoint. OpenCode uses the env:NAME substitution for
environment-backed values. The mcp block has no per-server tool allowlist;
restrict exposure in the ERPBridge registry and use approval controls for
writes. Client-side, you can hide tools through the tools config with glob
patterns, for example "tools": { "erpbridge_*": false }. Restart the
OpenCode session after changing the config; opencode mcp list shows
connection status.
OpenClawโ
OpenClaw manages client-side MCP definitions with openclaw mcp. Use the canonical streamable-http transport value, not the legacy SSE default.
Set ERPBRIDGE_MCP_TOKEN in the OpenClaw gateway environment:
openclaw mcp set erpbridge '{"url":"https://<erpbridge-host>/mcp/","transport":"streamable-http","headers":{"Authorization":"Bearer ${ERPBRIDGE_MCP_TOKEN}"},"toolFilter":{"include":["list_employees","list_departments"]}}'
openclaw mcp doctor erpbridge --probe
Keep the variable in the gateway trusted environment or supported secret configuration, not a workspace file. On versions that do not expand environment variables in HTTP headers, use that version's secret-reference mechanism and do not replace the placeholder with a committed token. OAuth is not appropriate for ERPBridge's static bearer-token mode.
Use openclaw mcp show erpbridge --json to inspect the saved definition. Run openclaw mcp reload or restart the owning gateway after changing it. For local stdio, use:
openclaw mcp add erpbridge-local --command erpbridge-server --arg --stdio --env ERP_PRIMARY_KEY=$ERP_PRIMARY_KEY
openclaw mcp doctor erpbridge-local --probe
Hermes Agentโ
Hermes uses mcp_servers in its YAML config, commonly ~/.hermes/config.yaml.
Remote Streamable HTTP:
mcp_servers:
erpbridge:
url: "https://<erpbridge-host>/mcp/"
headers:
Authorization: "Bearer ${ERPBRIDGE_MCP_TOKEN}"
tools:
include: [list_employees, list_departments]
resources: false
prompts: false
Hermes supports tools.include and tools.exclude filtering. Keep the token in ~/.hermes/.env or another supported secret scope and reload MCP with /reload-mcp.
Local stdio:
mcp_servers:
erpbridge-local:
command: "erpbridge-server"
args: ["--stdio"]
env:
ERP_PRIMARY_KEY: "${ERP_PRIMARY_KEY}"
tools:
include: [list_employees, list_departments]
HTTP bearer authentication does not apply to this local process.
Reload and troubleshootโ
- Codex: run codex mcp list; restart the TUI or IDE extension if needed.
- OpenCode: run opencode mcp list; restart the OpenCode session.
- OpenClaw: run openclaw mcp doctor erpbridge --probe, then reload or restart.
- Hermes: run /reload-mcp in the active session.
| Symptom | Check |
|---|---|
| 401 Unauthorized | The token is missing, expired, revoked, or unavailable to the agent process. Confirm Authorization: Bearer is sent and the token has mcp. |
| 403 Forbidden | The token lacks the mcp scope, or the operation is outside its role or tool policy. |
| HTTP client cannot connect | Use the exact https://erpbridge-host.example/mcp/ URL, verify GET /mcp/health, and check reverse-proxy forwarding of POST, GET, Authorization, Mcp-Session-Id, and MCP-Protocol-Version. |
| Tools list is empty | Check active ERPBridge tools and client-side filters. |
| stdio parse errors | Start with --stdio and make sure that no wrapper prints to stdout. ERPBridge writes startup diagnostics to stderr in stdio mode. |
| Upstream ERP calls fail | Check ERP_BASE_URL and the environment variable named by each tool credentialRef. |
See Connectivity and transport and API tokens.
Management MCP serverโ
erpbridge-server --stdio serves published ERP tools. To let an agent manage
ERPBridge itself, register a second, separate server that starts the
bridgectl mcp --stdio command:
[mcp_servers.erpbridge_manage]
command = "/usr/local/bin/bridgectl"
args = ["mcp", "--stdio", "--context", "staging"]
env_vars = ["BRIDGE_API_TOKEN"]
The management server exposes inspection, local validation, and generation by default. Write operations need an explicit startup group, and the session is pinned to the context selected at launch. See the management MCP server guide for the tool catalogue, the write groups, agent configuration examples, and recovery after an unknown write outcome.