MCP integrations
Connect HTTP or command-based tool servers, authenticate them, and control exposed tools.
Model Context Protocol (MCP) servers expose tools from other systems to the agent. Configure them under Settings → Integrations. MCP servers are gateway-wide: the configured catalog is available to the installation's agents, rather than being a private connector for one profile.
Choose a transport
| Transport | Configuration | Execution location |
|---|---|---|
| HTTP | Server URL and authentication | The URL is contacted by the gateway |
| stdio | Command, arguments, optional environment | A process launched on the gateway machine |
For a server gateway, localhost means the server or container, not your laptop. A command-based server must be installed where the gateway can launch it. Adding a stdio command does not run it on a selected Jian Remote machine.
HTTP authentication
Supported choices are none, headers, and OAuth.
- Headers let you configure the authorization scheme the service requires, including a bearer token or a service-specific header.
- OAuth opens the service's sign-in flow. The gateway stores its authorization in the vault.
- If the authorization server has no dynamic client registration, configure a preregistered client ID and, where required, its client secret. Use the callback address shown by Jian when registering it.
OAuth applies to HTTP servers, not stdio transport. Ensure the gateway's public callback address and proxy scheme are correct before diagnosing a provider as broken.
Command-based servers
Configure an executable, its argument list, and only the environment values it needs. The contract permits up to 30 arguments and 20 environment entries per server. Do not place secrets directly in a public command example; store them using the integration's secret fields.
A command server is executable code running on the gateway machine. Review its origin and installation procedure. The model's access to its tools is not evidence that the process is sandboxed like a built-in profile shell command.
Test, discover, and restrict
Use the panel's connection test. It reports reachability, discovered tools, an error if present, or a sign-in URL when authentication is required. A server can be reachable but still refuse one particular tool because that account lacks access.
Jian can store disabled tool names for a server; disabled tools are not offered to agents. Use this to limit the catalog to capabilities you intend to provide. Server names must be unique in the installation.
At runtime the agent searches the MCP catalog and loads specific tools. It does not need every remote tool definition in every model request.
Approval behavior
A server tool annotated readOnlyHint: true is treated as read-only by the action guard. Other MCP calls are considered service actions and follow conversation protection. That annotation is the server's declaration, which is another reason to connect servers you trust.
Service credentials determine the actual accessible data. A natural-language instruction cannot compensate for overly broad authorization.
Common failures
| Failure | Inspect |
|---|---|
| Command not found | The gateway's executable paths and installed package |
| Works on your laptop, not on the server | Which machine/container is resolving the URL or command |
| Sign-in returns to the wrong host | Public URL, callback registration, forwarded HTTPS scheme |
| Server appears but a tool is missing | Disabled tools, server catalog, runtime discovery |
| Private endpoint is refused | Host-admin private-origin policy; see configuration |