MCP
Connect Jio to Codex and other MCP-capable clients through the local stdio bridge.
Overview
The Model Context Protocol (MCP) lets an AI client discover and call external tools. Jio runs a local stdio bridge that presents remote workspace and code-execution tools to any compatible client.
MCP client → local Jio bridge → trust check → remote Jio Core sandboxUnlike a hosted MCP service, Jio does not give the client a public server URL or API key. The client launches the local jio executable. That bridge reads a local policy and identity, performs the selected trust check, and only then sends workspace plaintext to the remote endpoint.
MCP is the interoperability layer
MCP does not create Jio's security guarantees. Trust comes from the locally selected mode, transport and attestation checks, and the isolation enforced by the remote runtime.
Setup
Before installing MCP, complete one successful CLI workflow with an existing .jio/jio.toml policy file. This proves that the identity, policy, endpoint, and remote session work independently of the agent client.
Codex
Install Jio into the selected project's Codex configuration:
jio mcp install --project . --config .jio/jio.toml \
--identity .jio/identity.json --jsonThe installer creates or updates only .codex/config.toml. It preserves unrelated project settings, records canonical absolute paths, writes no credential, and does not change user or global Codex configuration.
The generated entry has this shape:
[mcp_servers.jio]
command = "/absolute/path/to/jio"
args = [
"mcp",
"--config", "/absolute/path/to/project/.jio/jio.toml",
"--identity", "/absolute/path/to/project/.jio/identity.json",
]
required = true
startup_timeout_sec = 30
tool_timeout_sec = 180
default_tools_approval_mode = "writes"Codex loads project-scoped configuration only after the project is trusted. Restart the client after installation, then inspect its MCP server list before asking the agent to use Jio.
Other MCP clients
Client-specific configuration
MCP clients use different configuration files and process-launch conventions. Translate the fields below to your client's documented stdio-server format.
{
"mcpServers": {
"jio": {
"command": "/absolute/path/to/jio",
"args": [
"mcp",
"--config",
"/absolute/path/to/project/.jio/jio.toml",
"--identity",
"/absolute/path/to/project/.jio/identity.json"
]
}
}
}Use absolute paths because graphical clients and editor extensions may launch with a different working directory or PATH from your shell. Do not embed a private identity, secret value, or bearer token in the client configuration.
Verify the connection
Confirm discovery
Check that the client lists a jio MCP server and exposes the jio_* tool catalog.
Plan locally
Ask the agent to call jio_plan and report the environment, profile, TTL, trust mode, attestation posture, egress, and cost metadata without starting a session.
Start explicitly
Review the plan, then call jio_session_start. Tool discovery and planning do not allocate a worker by themselves.
Exercise the boundary
Read a known file, run a harmless bounded command, inspect jio_git_diff, and verify that a forbidden operation returns a structured policy rejection.
Available tools
The local bridge can list its tool catalog without contacting or allocating a worker. A deployment exposes tools according to its runtime and policy.
| Group | Tools | Purpose |
|---|---|---|
| Planning and lifecycle | jio_plan, jio_status, jio_session_start, jio_session_renew, jio_session_stop | Inspect and control the bounded remote session |
| Workspace | jio_list, jio_search, jio_read, jio_write, jio_apply_patch | Discover and modify files below the remote workspace root |
| Execution and review | jio_exec, jio_git_diff, jio_sync_back | Run bounded commands, review changes, and apply an approved remote delta locally |
| Artifacts | jio_artifact_export, jio_artifact_pull | Create and retrieve explicit content-addressed outputs |
| Secrets | jio_secret_list, jio_secret_delete | Inspect secret metadata or delete a name without exposing its value |
| Services | jio_service_start, jio_service_status, jio_service_logs, jio_service_stop | Operate named private services with bounded logs and lifecycle |
jio_sync_back and jio_artifact_pull are handled by the local bridge because they publish content onto the local machine. Secret values can be entered only through interactive jio secret set; Jio deliberately does not expose a secret-value MCP tool.
Troubleshooting
Resources
- Use the Jio CLI to validate and operate the same policy without an agent client.
- Use the Jio Compute skill to teach compatible agents the policy-first workflow.
- Review MCP tools for capability and result-contract guidance.