bridgectl MCP management server
bridgectl mcp --stdio serves ERPBridge management operations to an MCP
client, such as an AI coding agent.
This command is a management server. It manages the local API registry and
the configured ERPBridge deployment. It is not the runtime server: use
erpbridge-server --stdio or <erpbridge-host>/mcp/ to call published ERP
tools.
Windows clientsโ
See management MCP on Windows for escaped Windows executable paths, direct argument arrays, and host-environment credential forwarding. Do not put token values in client configuration. Native Ctrl+C shutdown and default-browser launch require manual Windows checks; Linux SIGTERM behavior is unchanged.
Start a sessionโ
bridgectl mcp --stdio
bridgectl mcp --stdio --context staging
bridgectl mcp --stdio --context staging --allow-write registry,resources
The command requires --stdio and rejects positional arguments. Start one
process per agent configuration. The process stops when its input ends or it
receives an interrupt or termination signal.
Stream contractโ
Stdout carries the MCP JSON-RPC stream. Every line on stdout is one complete MCP message.
Diagnostics and startup failures use stderr. This rule also applies when the
client sets the global -o json flag: the JSON error document is written to
stderr, so stdout always stays a valid protocol stream.
Session pinningโ
A session is pinned to the context and credential that were resolved at launch. The adapter captures the context name, the management endpoint, the MCP endpoint, and the bearer credential once, then passes those fixed values to every operation it runs.
Consequences:
- Changing the saved default context with
bridgectl context setdoes not retarget a running session. The session keeps using its launch-time endpoints and credential. - Changing an endpoint or credential in the configuration file, or through
BRIDGE_*environment variables, does not affect a running session. - Restart the process to adopt changed endpoints or credentials. There is no active-session credential refresh.
- A child operation that cannot load the pinned context fails with
MCP_CONTEXT_CHANGED. It never falls back to another saved context.
The guard covers empty values as well. A session that started without a credential cannot silently acquire a newly configured one.
Permissionsโ
By default the session exposes inspection, local validation, and generation only. A write operation requires the operator to approve its group at launch.
| Group | Allows |
|---|---|
registry | API registration and credential-reference changes |
resources | Applying tool, plugin, and binding manifests |
destructive | Deletion, deactivation, token revocation, and cache flush |
probe | Server-side registered API tests, which can cause downstream effects |
context | Changing the saved default context |
--allow-write is repeatable and accepts a comma-separated list. There is no
wildcard. An unknown group name is a startup error.
Approval has these limits:
- A tool from a group that was not approved is neither advertised nor callable.
- Local approval does not grant remote permission. The ERPBridge deployment authorizes each request independently, and a local group never elevates a token.
- The local trust boundary is the operating-system identity of the process. Using stdio does not add a second authentication layer.
- Exact-target confirmation prevents accidental target mismatch. It is not proof of human consent. Configure approvals in the agent host as well.
Approved toolsโ
These tools require the stated group. Each one also requires confirmContext
to equal the pinned context and confirmTarget to equal the canonical target
listed below.
| Tool | Group | Canonical target |
|---|---|---|
bridgectl_api_register | registry (and destructive when force is true) | the registration name |
bridgectl_api_set_credential_ref | registry | the API name |
bridgectl_api_test | probe | the API name |
bridgectl_tool_apply | resources | the manifest name, or name@version |
bridgectl_tool_delete | destructive | name@version |
bridgectl_plugin_apply | resources | the manifest name, or name@version |
bridgectl_plugin_delete | destructive | name@version |
bridgectl_binding_apply | resources | the manifest binding name |
bridgectl_binding_delete | destructive | the binding name |
bridgectl_token_revoke | destructive | the token identifier |
bridgectl_cache_flush | destructive | tool:<name>, module:<name>, or all |
bridgectl_context_set | context | the requested context name |
Registration accepts an explicit empty authType, which registers an API with
no authentication.
A mismatch performs no child execution, and nothing is staged before the
confirmation passes. bridgectl_cache_flush accepts exactly
one selector: tool, module, or all. bridgectl_tool_delete,
bridgectl_plugin_delete, and bridgectl_binding_delete deactivate by default
and only delete permanently when hard is true.
Write resultsโ
Most resource writes report the target, effect: "command_completed", and
verified: false. Registration also reports replaced. Cache flush instead
reports target, deleted, optional status, and verified; saved-context
selection reports savedDefault, activeContext, and verified. These results
report command completion, never independent reconciliation or verification.
Read back the exact target before claiming the change is verified.
When a launched write fails, times out, is cancelled, exceeds its output limit,
or returns output the adapter cannot interpret, the result is
outcome_unknown rather than a specific failure, because the change may already
have been applied. Read the target resource before retrying. The adapter never
retries a write automatically.
Only two failures report a specific code, because both are provably refused
before the command runs: a rejected argument vector, and a
context_changed precondition from the session guard.
A server-side probe that completes and reports a failed result is a finished
observation, not an unknown outcome. It returns probe_failed with the HTTP
status, content type, and latency.
Saved default contextโ
bridgectl_context_set changes only the saved default context in the
configuration file, and it only accepts a context that is already saved. It
preserves environment placeholders, stored values, and unknown fields, and
writes the replacement with mode 0600. If the file changed while the update was
being prepared, the update is refused instead of overwriting the other change.
The running session keeps its pinned context, so this tool cannot retarget it.
Tool catalogueโ
A session without --allow-write exposes these tools:
| Tool | Operation |
|---|---|
bridgectl_context_list | List saved contexts, marking the one pinned to this session |
bridgectl_api_list | List the APIs registered in the local registry |
bridgectl_tool_get | Read one tool, or list tools |
bridgectl_tool_generate | Generate the tool manifest for a registered API |
bridgectl_tool_validate | Validate one tool manifest locally |
bridgectl_plugin_get | Read one plugin, or list plugins |
bridgectl_plugin_validate | Validate one plugin manifest locally |
bridgectl_binding_get | Read one plugin binding, or list bindings |
bridgectl_binding_validate | Validate one plugin binding manifest locally |
bridgectl_token_list | List API token metadata |
bridgectl_cache_stats | Read tool cache statistics |
bridgectl_log_stats | Read counts by log level and by tool |
Every tool returns one JSON object with schemaVersion, operation, context,
success, and either data or a safe error object. Failures set the MCP tool
error flag. MCP initialization reports the same release version as
bridgectl --version, so clients can identify the installed management server.
A read tool reports a resource that the selected deployment does not hold as
not_found, and a rejected credential as authentication_required, because the
managed child now checks the control-plane status before it decodes a typed body. The
adapter maps these by code and never reads child prose.
Tool, plugin, and binding inventories return data.items as an array, including
[] when the inventory is empty. A named get returns data.item and omits
data.items.
Result redactionโ
Inspection results are an allow-list, not a copy of the command output. They
omit credential fields, literal authentication header fields, schema defaults
and examples, raw endpoint URLs, plugin configuration, API token values, and
raw log messages. Retained descriptions, usage text, and schema enum values
are not arbitrary-content redaction. Review those values before sharing or
persisting them; redacted: true is not proof that all retained text is safe.
- Endpoint identity is reported as a neutral host label, so an operator can tell deployments apart without exposing paths or credentials.
- Schema declarations are preserved, including a property named
passwordortoken, so a manifest stays reviewable. Retained descriptions and enum values still require review. - Inspection results are marked
redacted: trueand are not round-trippable. Usebridgectl_tool_generateto obtain an applicable manifest. - Generation returns the executable manifest, because applying it is the purpose of the operation. The adapter refuses to return a manifest that contains a literal credential value or an unsafe endpoint.
Argument rulesโ
- MCP tool argument schemas are strict: an unknown argument is rejected before any command runs. Manifest validation is resource-specific; tool manifests do not universally reject unknown resource fields. Remove unsupported fields and validate the reviewed resource rather than relying on strictness.
- Strings are length-bounded, and a value may not start with
-, so a caller cannot inject an option. Tool deletion encodes the name and version as literal query values. Characters such as&cannot change the confirmed target or turn a soft delete into a hard delete; permanent deletion requireshard: true. - Manifests are one inline JSON object. Paths, directories, URLs, YAML streams, and arrays are rejected.
- Manifest tools do not accept embedded credential values. They reject a
kindthat does not match the tool, an endpoint with credentials in its userinfo or query, and a concrete default or example for a credential-like schema property. A schema declaration is still allowed. - Endpoint paths require the canonical field spellings
spec,execution, andendpoint. Case aliases such asSpecorEndpoint, including an alias beside a canonical field, are rejected before staging. - Credential screening shares the log redaction key policy. It rejects literal
values under names such as
client_secret,access_token, andprivate_key, including case variants and underscore-prefixed forms such asupstream_access_token. LogicalcredentialRefandcredentialSourcefields remain allowed. - Remote OpenAPI fetch,
$refresolution, output directories, and file writes stay in the manual CLI.
Validation resultsโ
A manifest that fails local validation returns invalid_arguments with an
adapter-owned message. The command's own validation text is not forwarded,
because child output is never trusted. Run the same validation with the
bridgectl CLI to see the exact reason.
Execution limitsโ
- One operation runs at a time. A concurrent call returns a busy result.
- Each operation has a 30-second deadline.
- A child process never receives the MCP input stream, a shell, a caller-chosen executable, a caller-chosen working directory, or a caller-chosen file path.
- Captured output, inline manifests, and incoming protocol messages are bounded. An oversized stream ends that operation; an oversized protocol message ends the session.
- Manifests are passed as a single inline JSON object. The adapter stages them in a private temporary directory and removes them afterwards.
Limits of this releaseโ
- Only the catalogue above is exposed. There is no generic command tool, no shell, and no filesystem or URL access.
- Reads report what the pinned deployment returns. They do not prove that an ERP endpoint is reachable.
- Log statistics summarise the deployment's recent events. Log messages are never returned.
- Token creation stays in the manual CLI, so a new credential value never enters an agent conversation.
- Local validation reports that a resource failed, not why. Run the same
validation with the
bridgectlCLI to see the exact reason. - Concurrent context edits from another process can still race the final rename. Do not run two context edits at the same time.
Interrupted writesโ
A write operation that is cancelled, times out, or cannot be interpreted is
reported as outcome_unknown. The adapter does not claim that the operation was
rolled back and does not retry it. Read the target resource before retrying.
Connect a coding agentโ
Register the management server separately from the runtime server. The runtime server exposes published ERP tools; the management server exposes the catalogue above. Use different names so a grant is never ambiguous.
Use an absolute path to the bridgectl binary, keep the token in the host
environment rather than in the configuration file, and start with the read-only
default. These examples are documentation only: the adapter never edits a
coding-agent configuration and never launches an agent.
Codex CLIโ
[mcp_servers.erpbridge_manage]
command = "/usr/local/bin/bridgectl"
args = ["mcp", "--stdio", "--context", "staging"]
env_vars = ["BRIDGE_API_TOKEN"]
enabled_tools = ["bridgectl_context_list", "bridgectl_api_list", "bridgectl_tool_get"]
env_vars forwards host environment variables to the child process, so the
credential stays outside the configuration file. Add write groups to args
only for the deployment where they are intended:
[mcp_servers.erpbridge_manage]
command = "/usr/local/bin/bridgectl"
args = ["mcp", "--stdio", "--context", "staging", "--allow-write", "registry,resources"]
env_vars = ["BRIDGE_API_TOKEN"]
default_tools_approval_mode = "prompt"
For the runtime server, keep a separate entry that starts erpbridge-server --stdio or points at https://<erpbridge-host>/mcp/.
Claude Codeโ
claude mcp add --transport stdio erpbridge_manage -- \
/usr/local/bin/bridgectl mcp --stdio --context staging
With an explicit write grant:
claude mcp add --transport stdio erpbridge_manage -- \
/usr/local/bin/bridgectl mcp --stdio --context staging --allow-write registry,resources
Keep BRIDGE_API_TOKEN in the host environment. Claude Code also supports an
--env option; prefer the host environment when a secret store already provides
the value.
What the grant does and does not doโ
- It governs only this local process. The ERPBridge deployment authorizes every request again on its own.
- It is not human approval. Confirmation fields prevent a target mismatch; they do not prove that a person reviewed the call. Configure approvals in the agent host as well.
- It does not cover token creation, OpenAPI import, file output, or arbitrary commands. Those stay in the manual CLI.
- It does not survive a restart of the MCP process. Adding or removing a group requires a new process.
Restart and recoveryโ
Endpoints, the credential, and the write grants are captured when the process starts. After you change an endpoint, a credential, or a grant, restart the MCP process. A running session keeps its pinned selection and never falls back to another saved context.
If a write reports outcome_unknown, read the target resource before retrying.
The adapter does not roll back and does not retry, so a second attempt could
repeat an effect that already happened.
Related documentationโ
- Agentic tools MCP integration covers runtime MCP access to published ERP tools.
- Connectivity and transport covers transports, endpoints, and authentication.
- ERPBridge Console covers the read-only local web console.