Documentation / MCP and ACP
Yuli as an MCP server
How yuli-mcp exposes the whole IDE to your terminal agent, how it connects and what happens when Yuli is closed.
Yuli ships with yuli-mcp, a Model Context Protocol (MCP) server. Through it, Claude Code, Kiro, Codex and Antigravity use the full IDE as tools: build, test, verify, navigate the code, query the database, drive Web Studio and follow the mission.
In Subscription mode there is nothing to configure: Yuli registers yuli-mcp with each agent when it starts it. This page explains how it works under the hood.
How it connects
Your agent ──stdio / JSON-RPC 2.0──▶ yuli-mcp ──TCP 127.0.0.1 + token──▶ Yuli (engine)
| Piece | Details |
|---|---|
| Transport with the agent | MCP over stdio, JSON-RPC 2.0, one JSON message per line. |
| Protocol versions | 2025-06-18, 2025-03-26 and 2024-11-05. |
| Capabilities | Tools. Resources and prompts are answered empty. |
| Connection to the IDE | TCP socket on loopback only (127.0.0.1), on a random port. |
| Authentication | A Yuli-specific session token on every request. It is not an Anthropic credential or a credential from any provider. |
| Long-running tasks | Sends progress notifications. A call can last up to 40 minutes. |
The connection file
On startup, the engine writes endpoint.json with the port, the token and its process. On Linux and macOS only your user can read the file.
| System | Path |
|---|---|
| Windows | %APPDATA%\.yulicode\claude-bridge\endpoint.json |
| macOS | ~/Library/Application Support/.yulicode/claude-bridge/endpoint.json |
When Yuli opens an agent's terminal, it also passes the port and the token through environment variables, along with the project root.
A stable binary
Agents launch a stable copy of yuli-mcp in Yuli's local folder (on Windows, %LOCALAPPDATA%\.yulicode\bin\yuli-mcp.exe). It survives Yuli updates, so the agent's configuration doesn't break when you update.
If Yuli is closed
The yuli_* tools work while Yuli is open with that project. If it isn't:
- The tool list offers only
yuli_status, which explains why. - A call responds: “Yuli Code is not open (or this project isn't open in it). Open the project in Yuli and try again; the Yuli tools work while Yuli is running.”
- Hooks exit without blocking anything: your agent keeps working.
- The Claude Code status line shows
◆ Yuli · disconnected.
If /mcp in Claude Code shows yuli with an error, open the project in Yuli. The tools come back on their own.
Subcommands
| Command | Purpose |
|---|---|
yuli-mcp mcp --project <raíz> |
The MCP server. This is the default mode. |
yuli-mcp hook <Evento> --project <raíz> |
Forwards an agent hook to Yuli. |
yuli-mcp gate --project <raíz> --stage <etapa> |
Runs the quality gate. Returns 0, 1 or 2. |
yuli-mcp --version |
Shows the version. |
The --agent kiro|codex|antigravity option identifies which agent is calling. That way each agent has its own conversation, mission and changes window.
How many tools your agent gets
It gets everything Platform mode can use in that project: a core of named tools plus the rest of the engine. The total depends on the project: tools for a capability that isn't active are hidden (for example, the database tools if there are no connections, or the Sonar tools if it isn't linked).
The exact number appears in the agent bar: Connected to Yuli · N tools.
Only six internal tools from Yuli's own loop are left out: proposing changes, launching subagents, searching tools, asking questions, publishing the plan and updating it. Your agent has its own, and its plan is mirrored in Yuli with yuli_progress.
See the catalog in Yuli tools.
The same guards
Every call goes through the same rules as Yuli's own agent:
- Authorization and approval cards in Yuli.
- Project hooks.
- Git, CI and DevOps only if you asked for them.
- Protected secrets.
- “Stop” means stop.
Results appear in Yuli's panels (Run, Tests, Problems) and count as verification.
External connectors
If you configured MCP servers in Yuli (Tools → MCP Servers…: GitHub, GitLab, Jenkins, CloudBees, Jira, SonarQube…), your agent also receives them through yuli-mcp, as yuli_mcp_<servicio>_<herramienta>. Read tools run freely; tools that write ask for approval and never run unattended.