How to Connect Laya to a Coding Agent Over MCP

Quick answer
Install the extra with pip install “laya[mcp]” and run laya-mcp-server; it speaks MCP over stdio, not HTTP.
Configure it in the client’s mcpServers block with LAYA_DEVICE and optional LAYA_MODELS; the client starts the process.
Start with laya_status and laya_route, then use laya_predict for typed choice, score, and noul questions.
The agent gets a local judgment tool; it still owns the action, so keep permissions and side effects in your code.
If the tools do not appear, run the server manually and read stderr before changing the client configuration.

What does the Laya MCP server expose?

The server turns Laya’s decision engine into a set of MCP tools. laya_status reports the device, loaded checkpoints, readiness, and versions. laya_route selects a checkpoint without running a forward pass. laya_predict runs typed questions and returns the answers, routing metadata, latency, and device. There are also batch, preset, schema-driven, shortlist, tournament, and long-document tools for larger jobs.

The transport is stdio: the MCP client starts the server as a child process and talks over standard input and output. There is no port to open and no service to keep running separately. That is convenient for a local coding agent, and it means the model’s lifecycle is tied to the agent session. The client owns the process; you own the configuration and the checkpoint cache.

Step 1 — install the MCP extra

Install the extra in the same virtual environment where you want the server to run. The core package does not install the MCP dependency. Check that the console script is on the path the client will use, or use the module form python -m laya.mcp.server if the client supports a command plus arguments.

python3 -m venv .venv
.venv/bin/python -m pip install "laya[mcp]"
.venv/bin/laya-mcp-server --help

Step 2 — configure the client

Add a named entry to the client’s MCP configuration. The command is laya-mcp-server, and the environment controls the device and which checkpoints are preloaded. The client launches the process, so there is no URL or port. If the client cannot find the command, use the absolute path to the virtual environment’s executable.

The default preloads the English and multilingual checkpoints and leaves typed-decisions lazy. LAYA_MODELS limits what is loaded; LAYA_DEVICE chooses a device; LAYA_PRELOAD=0 switches to lazy loading. Keep the environment minimal. If the agent does not need the multilingual checkpoint, do not pay its memory cost in every session.

{
  "mcpServers": {
    "laya": {
      "command": "laya-mcp-server",
      "env": {
        "LAYA_DEVICE": "cpu",
        "LAYA_MODELS": "english,multilingual",
        "LAYA_PRELOAD": "1"
      }
    }
  }
}

Step 3 — verify the tools appear

Start a new agent session after changing the configuration. Ask the agent to list its tools, or call laya_status directly. A healthy server reports the device, the loaded checkpoints, and readiness. Then call laya_route on a sample state. It returns the selected checkpoint and the reason without downloading weights, which is a cheap way to confirm that routing sees the language and task you expect.

If the tools do not appear, the process probably failed to start. Run laya-mcp-server manually and read stderr. A missing MCP dependency, an unsupported device string, a checkpoint download failure, or a Python environment mismatch are the usual causes. A stdio server has no startup screen, so silence from the client usually means the process exited immediately.

Step 4 — use a typed decision

A useful first tool call is a triage decision: send one state and a small question set with a department choice and an urgency noul. The tool returns the typed answers, probabilities, routing metadata, and latency. Read the probabilities, not only the winning label; a flat distribution is the signal to ask the agent for more context or hand the case to a human.

Keep the question set small and atomic. The agent can call the tool repeatedly, but each call is a judgment, not an action. A good pattern is to use Laya to decide which of three tools the agent should consider, then let the agent call the chosen tool with its own validation. Do not let the decision tool execute the action it is judging.

{
  "state": {
    "body": "The checkout page returns a 500 for every customer and we are losing orders."
  },
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which queue should handle this?",
      "criteria": {
        "billing": "payments, invoices, refunds",
        "technical": "bugs, outages, integrations",
        "human_review": "ambiguous or sensitive"
      }
    },
    "urgent": {
      "type": "noul",
      "instructions": "Does this describe an outage or lost revenue?"
    }
  }
}

Step 5 — keep the action in code

An MCP tool gives the agent a capability, and the agent’s model decides when to use it. That is useful for judgment and dangerous for authority. Keep the tools that change state behind their own allow-lists, confirmations, and idempotency checks. The Laya prediction should inform the agent’s plan, not authorize a shell command, a file deletion, or a refund.

Log the tool call and its answer, including the routing decision and the probabilities. The log is how you find the cases where the agent trusted a low-confidence answer or asked the wrong question. Review a sample of the tool calls after the first week; the question design usually needs one revision once you see real inputs.

Where this bites vibecoders
The appeal of an MCP server is that the agent can use the model without you writing an integration. The risk is that the agent treats a tool call as permission. Give it a judgment tool, not an action tool, and keep the action behind your own code. If the agent can call laya_predict and then run any shell command, the decision layer is not a guardrail; it is decoration.

Where AI coding assistants get this wrong

Installing the core package without the mcp extra and wondering why the command is missing.
Using a venv-relative command without an absolute path the client can resolve.
Preloading every checkpoint on a small machine.
Letting the agent use a high-confidence decision as authorization to act.
Ignoring a flat probability distribution because the winning label looks plausible.
Changing the client config without restarting the session.

Checklist

Install laya[mcp] in the environment the client will use.
Add laya-mcp-server to the client’s mcpServers block.
Set LAYA_DEVICE and limit LAYA_MODELS.
Start a new session and call laya_status.
Call laya_route on a sample state.
Make one typed prediction and inspect the probabilities.
Keep the action, permissions, and confirmations in code.

FAQ

Does the Laya MCP server use HTTP?

No. It speaks MCP over stdio, and the MCP client starts it as a child process. There is no port to open. If you need a long-running HTTP service, use laya-serve instead, which exposes a Jev-compatible /v1/systemone endpoint.

Which MCP clients work with Laya?

Any client that supports stdio MCP servers and the mcpServers configuration shape. The exact file location and restart behavior vary by client. If the client cannot launch a console script, use the equivalent python -m laya.mcp.server command with the virtual environment’s Python.

Why do the Laya tools not appear?

The process probably exited before the handshake. Run laya-mcp-server manually and read stderr. Common causes are a missing mcp dependency, a bad LAYA_DEVICE value, a checkpoint download failure, or the client using a different Python environment. Fix the process first, then the client configuration.

Can the agent use Laya to decide whether to run a command?

It can ask for a probability that a command is destructive or off-task, and that is useful as one input. It should not use the answer as permission. The command still needs an allow-list, a sandbox, and a confirmation policy in your code. A model judgment is evidence, not authorization.

How do I choose between laya_predict and laya_preset?

Use laya_predict when you have your own question set and want typed answers. Use laya_preset for a quick built-in workflow such as triage, email, guard, moderation, or router. Presets are useful for exploration, but inspect their questions and validate them on your data before using them as an application policy.