Connectivity and transport guide

ERPBridge supports multiple transport protocols. It works with AI agents, IDEs, and developer tools such as Postman.

1. Streamable HTTP

This transport follows the MCP Streamable HTTP specification. It suits stateless or web-friendly environments. It is the recommended way to connect Postman and other modern MCP clients.

• Base URL: http://localhost:8080/mcp/
• Handshake: POST /mcp/ with a JSON-RPC initialize request
• Transport specification: MCP 2025-11-25. The server negotiates older supported protocol versions for compatible clients.
• Features:
  • Request and response via standard POST.
  • Session management via the Mcp-Session-Id header.
  • Full CORS support for browser and desktop clients.

Set CORS_ALLOWED_ORIGINS to a comma-separated list of browser origins. An allowed preflight is processed before bearer authentication; the following MCP request still requires authentication when API_AUTH_TOKEN is configured. In open mode, the server keeps wildcard CORS behavior. CORS applies to /mcp/ only.

Postman configuration

• Transport Type: Streamable HTTP
• URL: http://localhost:8080/mcp/

Session lifecycle

The first request must be initialize. The server replies with a Mcp-Session-Id header that every subsequent request must include. See the MCP client guide for the full sequence.

2. stdio

stdio is the preferred transport for local integrations. The client starts ERPBridge Server as a child process.

• Best For: Claude Desktop, Cursor, and other IDE-integrated agents running locally.
• Usage: Run the server with the --stdio flag.

Start the stdio transport

erpbridge-server --stdio

The stdio stream reserves stdout for MCP JSON-RPC. ERPBridge writes its startup banner and diagnostics to stderr in this mode. HTTP bearer authentication does not apply to stdio; the child process receives upstream ERP credentials through its environment.

See the Agentic Tools MCP Integration guide for Codex CLI, OpenCode, OpenClaw, and Hermes Agent examples.

No session ID needed

The stdio transport does not use Mcp-Session-Id. The process boundary itself is the session.

3. Direct API

The server exposes direct HTTP endpoints for internal management, performance monitoring, and the bridgectl CLI. These do not require a full MCP handshake.

Endpoint	Method	Description
/apis/erpbridge.io/v1/tools	GET/POST/DELETE	Apply, list, and delete tool definitions (Control Plane).
/api/tools/invoke	POST	Directly invoke an MCP tool.
/api/cache/stats	GET	Retrieve tool cache performance metrics.
/api/cache/flush	GET	Flush specific or all cache entries.
/api/logs/stream	GET	Real-time structured log stream (SSE).
/api/logs/recent	GET	Fetch recent log history in JSON format.

When authentication is enabled, the registry, direct invoke, cache, and token routes are admin-only. Log routes accept the logs scope, /metrics accepts the metrics scope, and /mcp/ accepts the mcp scope. /mcp/health stays open.

For the full endpoint reference, see the REST API reference.

4. Protection and limits

ERPBridge includes built-in protection for underlying ERP systems.

• Rate limiting: Tool execution uses a token bucket. Authenticated HTTP requests are keyed by token principal; unauthenticated stateful MCP requests use their session, and stdio uses its process fallback.
• Default limits: 10 requests per second with a burst of 20 (configurable via RATE_LIMIT_RPS and RATE_LIMIT_BURST).

Excess direct /api/tools/invoke calls return HTTP 429, stable error RATE_LIMITED, and a whole-second Retry-After value. Streamable HTTP MCP tools/call requests remain HTTP 200 and carry result.isError=true. tools/list is not subject to tool-execution throttling.

MCP protocol failures use JSON-RPC errors. Malformed JSON uses -32700, invalid requests use -32600, unsupported methods use -32601, invalid protocol parameters use -32602, and unexpected server failures use -32603. Valid tool calls that fail during execution return isError: true instead. These results may include the namespaced com.erpbridge/error metadata with a safe error type, retryability, and a bounded retryAfterMs value.

ERP retries are bounded by three attempts and a 30-second overall deadline. Retry-After is honored when supplied. Automatic retries are limited to GET, HEAD, and OPTIONS so POST, PUT, PATCH, and DELETE operations are not blindly replayed without an idempotency mechanism.

5. Connector resilience

Every outbound call to an upstream ERP goes through a resilient client with three layers of defense. This helps existing ERP systems remain stable when AI agents send heavy or bursty workloads.

• Request timeout: 15 seconds per HTTP request.
• Retry with backoff: transient failures are retried up to 3 attempts with a 500ms base delay plus up to 100ms of random jitter. Network errors and HTTP 429 / 5xx responses are retried; other responses are returned immediately.
• Circuit breaker: after at least 5 requests with a failure ratio of 60% or higher, the breaker opens and blocks further calls for 30 seconds. While open, a maximum of 3 test requests probe the ERP before the breaker closes again. Every state change is logged.

Why it matters

Without resilience, one slow or failing ERP endpoint would stall every AI agent that depends on it. The circuit breaker fails fast during outages and the retry policy absorbs transient spikes.

6. Monitoring and health

Standard endpoints for system health and observability.

• Health check: GET /mcp/health (returns {"status": "ok"})
• Metrics: GET /metrics (Prometheus formatted metrics)

Authenticated clients can open /api/logs/stream for SSE events. The server flushes headers before the first event and frames each event as data: <JSON>\n\n. The raw stream is distinct from the redacted Console BFF projection. A slow subscriber uses a bounded 100-event channel; new events are dropped when it is full.

Summary table

Client Type	Recommended Transport	Base URL / Method
Postman / Web	Streamable HTTP	http://localhost:8080/mcp/
Claude / Cursor	stdio	erpbridge-server --stdio
bridgectl / Scripts	Direct API	http://localhost:8080/api/
Prometheus	HTTP	http://localhost:8080/metrics