Tools and MCP servers

Agents act through tools. CLIO has a small set of built-in tools, and everything else comes from MCP servers. MCP, the Model Context Protocol, is an open standard for giving AI applications tools, data, and reusable prompts. Any server that speaks it can be connected to CLIO.

Built-in tools

CLIO ships two built-in tool servers:

• File system tools, such as fs_read_file and fs_propose_edit.
• Shell tools, such as shell_bash.

Domain tools are not built in. They come from MCP servers: the ones a blueprint declares, clio-kit servers for scientific data, and servers you add yourself. The installer provisions clio-kit for you when uv is available, and blueprints start its servers with commands such as clio-kit mcp-server geo.

A tool’s name starts with its server’s name. A server named geo that offers a geocoding tool shows up as geo_geocode. For that reason, a server name can only contain lowercase letters, digits, and hyphens, with no underscores.

Whether a tool needs your approval depends on the permissions in force, not on where the tool came from.

Add a server from the interface

1. Open Settings and choose MCP tools.

2. Choose Connect MCP.

3. Give the service a name, then choose a Connection type: Remote service takes a service address, and Local command takes an executable, its arguments, and optional environment variables.

4. Choose Connect MCP to confirm. CLIO checks the service before making its tools available to agents.

The list shows the connected services with their tools, resources, and prompts. Each service can be reconnected or disconnected.

Add a server in mcp.yaml

You can also declare servers in a file. The file has one top-level key, mcp_servers, that maps a server name to how to reach it.

.clio/mcp.yaml

mcp_servers:
  weather: uvx weather-mcp serve
  notion: https://mcp.notion.com/mcp

The short form is a single string:

• A command, split on spaces into a program and its arguments, starts a local server over standard input and output. Quote arguments that contain spaces.
• A URL starting with http:// or https:// connects to a remote server.

Environment variables

${VAR} is replaced with the value of an environment variable, and ${VAR:-default} uses default when the variable is unset or empty. A variable with no default that is unset marks that server as invalid, with a message naming the variable, and the other servers are not affected.

mcp_servers:
  files: npx -y @modelcontextprotocol/server-filesystem ${DATA_DIR:-/data}

Expansion applies to the command, its arguments, env values, the URL, and header values.

Mapping form

Use a mapping when a server needs environment variables, headers, or other settings.

A local server:

mcp_servers:
  lab-data:
    command: uvx
    args: [lab-data-mcp, serve]
    env:
      LAB_API_TOKEN: ${LAB_API_TOKEN}
    timeout: 60000

A remote server:

mcp_servers:
  catalog:
    url: https://tools.example.org/mcp
    headers:
      Authorization: Bearer ${CATALOG_TOKEN}

The keys:

Key	Applies to	Meaning
command	Local	The program to run. Required for a local server.
args	Local	A list, or a single string that is split on spaces.
env	Local	A mapping of environment variables for the server process.
url	Remote	The service address. Required for a remote server.
headers	Remote	A mapping of HTTP headers.
auth	Remote	An OAuth block, with type: oauth and client_metadata.
type	Both	stdio, http, streamable-http, or sse. If omitted, a mapping with a url and no command is remote and any other mapping is local.
timeout	Both	A time limit in milliseconds.
probe_timeout_retries	Both	How many times to retry when the first check of the server times out. A whole number, 0 or more.
always_load	Both	true to load the server’s tools up front. alwaysLoad also works.

Caution

Do not put secrets directly in the file. Reference them with ${VAR} and set the variable in the environment that starts CLIO.

Where servers are declared

The same server name can be declared in several places. They are merged by name, and the first of these wins:

1. The workspace file, <workspace>/.clio/mcp.yaml.
2. The user file, mcp.yaml in your CLIO configuration folder.
3. The mcp_servers field of the active blueprint’s AGENT.md.
4. The built-in tools.

• Directorymy-workspace/

  • Directory.clio/

    • mcp.yaml servers for this workspace only
    • hooks.json

Put a server in the workspace file when only one project needs it, and in the user file when you want it everywhere. A file that cannot be read is skipped with a warning, and the rest still load.

Servers from blueprints

A blueprint lists the servers it needs in mcp_servers in its AGENT.md, in the same short or mapping form. See Agent blueprints. An expert can then use the tools those servers provide. A blueprint can also package tool descriptors under tools/. Installing the blueprint records them without turning them on. Enabling one checks that the server responds and then makes its tools callable.

Lifecycle

CLIO does not start every server at launch. A server starts the first time one of its tools is called. Each workspace has its own set of running servers, and a set that has been idle for two minutes is stopped. By default at most two workspaces keep servers running at once. The next tool call starts what it needs again.

If a local server fails to start, CLIO reports the cause when it can, such as a command that is not on your PATH or a working directory that does not exist. Install the program, or give the full path in command, and reconnect the server.

If a server will not connect, see Troubleshooting.