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

1. Start ERPBridge and confirm GET https://erpbridge-host.example/mcp/health returns {"status":"ok"}.
2. Register and activate the MCP tools that the agent should use.
3. For protected HTTP deployments, create a token with the mcp scope and expose it to the agent through its environment or secret store.
4. 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.

Official client references

• Codex MCP configuration
• OpenCode MCP servers
• OpenClaw MCP CLI
• Hermes MCP configuration