AI Agent via MCP

Any MCP-compatible agent connects to a gibil server through the MCP protocol. The MCP server exposes lifecycle tools, VM tools, and background job tools, giving your agent full control over remote servers. Gibil uses standard MCP, so any compatible client works.

Setup

Run gibil init. It configures the MCP server automatically. For Claude Code, it writes to ~/.claude/.mcp.json. For other agents, add the MCP config manually:

{
  "mcpServers": {
    "gibil": {
      "command": "gibil",
      "args": ["mcp"]
    }
  }
}

Restart your agent to activate. It now has these tools:

Tool	What it does
`create_server`	Forge a new server (with repo, TTL, env vars)
`destroy_server`	Burn a server by name
`list_servers`	List all active servers with IPs and TTL
`extend_server`	Extend a server's auto-destroy timer
`vm_bash`	Run any shell command (supports `background: true`)
`vm_read`	Read files with line numbers and offset/limit
`vm_write`	Create or modify files
`vm_ls`	List directories, filter by glob pattern
`vm_grep`	Search file contents with regex
`vm_job_status`	Poll a background job for completion
`vm_job_list`	List all background jobs

What your agent can do

Your agent manages the full lifecycle (forge, work, burn) without leaving MCP:

Forge a server: create_server({ name: "task-1", repo: "...", ttl: "30m" })
Explore the repo: vm_ls, vm_grep, vm_read to understand the codebase
Write code: vm_write to create or modify source files
Run anything: vm_bash to install packages, run tests, build, deploy, git push
Run long tasks in background: vm_bash({ command: "pnpm build && pnpm test", background: true }) returns a job ID
Poll for results: vm_job_status({ job_id: "j-abc123" }) returns exit code + output when done
Iterate: read test output, fix code, run again. The code-test loop with typed tools
Burn when done: destroy_server({ name: "task-1" })

Why MCP over CLI mode

Both work. MCP is better when the agent needs to read and write files frequently:

Typed tools: vm_write({ path: "src/app.ts", content: "..." }) instead of shell escaping
Structured results: every tool returns parsed output with exit codes
No quoting hell: the MCP server handles SSH internally

In unbound mode (gibil mcp), the MCP server handles the full lifecycle: create, work, destroy. In bound mode (gibil mcp <name>), only VM tools are available.

Next steps

Use with AI Agents (full guide): CLI mode vs MCP mode comparison
Agent Code-Test Loop: the iteration pattern MCP enables
AI Agent Sandbox: patterns for autonomous agents

AI Agent via MCP

Setup

What your agent can do

Why MCP over CLI mode

Next steps

On this page