Skip to main content
Version: ERPBridge + bridgectl · v0.5.0-alpha.2

Frequently asked questions

MCP clients and transports​

Which MCP clients can connect to the server?

The server supports two transports:

  • Streamable HTTP for remote and web-based clients such as Postman at http://localhost:8080/mcp/
  • stdio for local agents (Claude, Cursor) by running the binary with --stdio

See the Connectivity and transport guide for session setup.

Which MCP protocol version does the server negotiate?

The server speaks MCP 2025-11-25 and negotiates older supported protocol versions during the initialize handshake. Clients send the initialize request to POST /mcp/, then continue with session-managed requests.

How do I connect from Postman?
  1. Send POST http://localhost:8080/mcp/ with Content-Type: application/json
  2. The initialize handshake creates a session
  3. Use the returned session ID in Mcp-Session-Id for subsequent requests, then call tools/list

The Postman setup in the repository shows the full flow.

Configure ERPBridge and bridgectl​

How do I configure the server?

Set the environment variables listed in the Environment variables reference. For local development, prefer make dev-up; it creates ephemeral MockERP credentials only when no credential source is supplied. Compose reads .env as input, so use --env-file .env and never source the file. The development path enables demo tools and keeps RedisInsight loopback-only.

How do I configure the CLI?

The CLI reads ~/.bridgectl/config.yaml. The file stores named contexts. Each context has server, mcp-server, erp-base, and an optional api-token value. New API registries are isolated at ~/.bridgectl/registries/<context>.json; listings are deterministic and scoped to the selected context.

For HTTP authentication, the CLI uses the --token flag first, then BRIDGE_API_TOKEN, and then the active context's api-token.

To switch contexts:

Switch contexts
bridgectl context list
bridgectl context set <name>

To override the address for one command:

One-off override
BRIDGE_MCP_SERVER=http://localhost:8080 bridgectl tool get

The configured mcp-server is a control-plane host root. The CLI strips only an exact /mcp or /mcp/ suffix. Other non-empty paths return CONTROL_PLANE_URL_INVALID; /mcp/ itself is the MCP transport, not a REST path. A legacy global registry is a stop condition. After confirmation, scrub legacy fields, then migrate the cleaned registry to one selected context with bridgectl api migrate-registry --context <name> --yes.

Why do bridgectl cache and bridgectl log fail with "connection refused"?

The default context points server at http://localhost:8082. Nothing listens there. Set BRIDGE_SERVER=http://localhost:8080, or edit the server value in ~/.bridgectl/config.yaml.

How do I enable debug logging?

Set LOG_LEVEL=debug on the server. You can also set per-component levels, for example LOG_LEVEL_MCP=debug.

How do I run the server in JSON log mode?

Set APP_ENV=production.

Do I need Redis?

No. The cache uses a bounded in-memory LRU when REDIS_URL is empty. Set CACHE_MEMORY_MAX_ENTRIES=0 to disable memory-cache storage. If REDIS_URL is set, Redis remains the selected backend even when it is unreachable; the server reports the backend error instead of silently using memory.

How does caching work and what is the default TTL?

The cache stores exact-match tool responses keyed by tool name, role, and request hash. By default responses do not expire (ttl: 0). Set a TTL in the server config to expire entries, or flush manually:

Flush the cache
bridgectl cache flush

See the Exact Match Caching guide.

When is a cached entry invalidated?

A tool schema can declare flushOn with a field path. When a tool call modifies that field, the server removes matching cache entries. To invalidate everything for a module, flush by module or use bridgectl cache flush.

How does the server protect ERP credentials?

Tool schemas reference credentials by name (credentialRef). The server resolves the reference from environment variables at call time, so schemas never contain raw secrets. Logs redact sensitive values: tokens, passwords, authorization headers, and PII, plus any value flagged with secret or pii tags. See the redaction reference.

Notifications and system tools​

What notifications does the server emit?

The server sends MCP notifications for long-running work:

  • notifications/progress — progress on tool calls
  • notifications/alert — alert-level events
  • notifications/message — informational messages
  • notifications/tool_deleted — when a tool disappears from the registry
What are the system tools?

Two development-only tools help verify the bridge:

  • system.progress_test — streams progress notifications
  • system.sensitive_log_test — exercises log redaction

They are absent from discovery unless MCP_ENABLE_TEST_TOOLS=true. Enable that flag only in the development Compose path. RedisInsight is also a local-only inspection aid and must remain loopback-bound or opt-in.

Errors and exit codes​

What do bridgectl exit codes mean?
  • 0 success
  • 1 general error
  • 2 bad arguments
  • 3 not found
  • 4 authentication failure
  • 5 conflict
  • 6 timeout
  • 7 precondition failed
How do I handle errors from the bridge in an agent?

Control-plane failures return a bounded JSON body with stable error, safe message, suggestion, and numeric code fields. Common recovery keys are CONTEXT_NOT_FOUND, LEGACY_REGISTRY, REGISTRY_CONFLICT, CONTROL_PLANE_URL_INVALID, VALIDATION_FAILED, AUTHENTICATION_FAILED, AUTHORIZATION_DENIED, UPSTREAM_UNREACHABLE, INSECURE_TRANSPORT, HEALTH_CHECK_FAILED, RECONCILIATION_FAILED, RESOURCE_NOT_FOUND, and API_PROBE_FAILED. Messages do not include upstream bodies, credentials, auth headers, or stack details. MCP execution failures keep the MCP result envelope and set isError: true.

Tools and schemas​

Where do tool schemas come from?

Generate a temporary draft from your ERP OpenAPI specification, then keep only the reviewed manifest as the applied source:

Generate and apply a reviewed manifest
bridgectl api register --context <context> --name erp --url http://localhost:8081 --module erp --description "Mock ERP" --credential-ref ERP_PRIMARY_KEY
bridgectl tool generate --context <context> --api erp -o yaml > /tmp/erpbridge-draft.yaml
bridgectl tool validate --context <context> -f manifests/erp/tools.yaml
bridgectl tool apply --context <context> -f manifests/erp/tools.yaml

make generate-tools applies one temporary YAML stream once and removes it. Do not treat generated schemas/ or per-tool JSON files as a second source of truth.

How do I update a tool?

Apply the new version with bridgectl tool apply -f <file>. The registry keeps multiple versions. MCP clients receive the latest stable version.

How do I hide a tool without deleting it?

Soft-delete it:

Soft delete a tool
bridgectl tool delete <name> <version>

The tool stays in the database. It no longer appears in tools/list.

How do I restore a soft-deleted tool?

Apply the schema again:

Restore by re-applying
bridgectl tool apply -f schemas/erp/<name>.json
How do I permanently remove a tool?
Hard delete a tool
bridgectl tool delete <name> <version> --hard
danger

A hard delete removes the tool from the database. You cannot restore it.

How quickly does the server pick up tool changes?

Within 10 seconds. The reconciliation controller ticks every 10 seconds. A tool applied over the API is visible immediately.

Authentication​

How does the server authenticate ERP calls?

Tool schemas reference a credential by name (credentialRef). The server resolves the reference from environment variables at call time. Schemas never contain raw secrets.

The mock-erp service accepts the configured token header, session cookie, or Basic Auth identity. Credential values are supplied through environment variables or an external secret file; they are not documented or stored in schemas.

See the MockERP Integration Contract for details.

Upgrades​

How do I upgrade ERPBridge?
  1. Pull the latest changes: git pull
  2. Rebuild the binaries: make build
  3. Restart the containers: docker compose up -d --build

The SQLite registry keeps its data when the migration succeeds. If the server cannot initialize the registry, inspect the startup error and correct the database path or permissions before you restart the server.

Where do I find release notes?

Troubleshooting​

Tool calls return internal server error

Check the server logs:

Server logs
docker compose logs erpbridge-server

Common causes:

  • The ERP service is unreachable. Make sure ERP_BASE_URL uses http://mock-erp:8081 inside Docker.
  • The tool endpoint path contains a secret pattern and was rejected.
  • The selected Redis or in-memory cache backend is unavailable. Inspect the server logs and run bridgectl cache stats.
Where do I get help?