> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Give your AI agents a new tool with an MCP server

> Add an MCP server to a Reliant project, hand its tools to agents through a preset, and use that preset in a workflow node that calls the new tool.

Your agents can call anything an MCP (Model Context Protocol) server exposes: a ticket system, an internal API, a database. In this guide you add a small MCP server to a project, give its tool to an agent through a preset, and run a workflow whose agent calls it. The server runs on your machine, beside the code, so it can reach whatever that machine can. [MCP servers](https://docs.reliantlabs.io/settings/mcp-servers.md) is the reference for the config file.

## Before you begin

* The `reliant` CLI, v1.21 or later, signed in ([Sign in and tokens](https://docs.reliantlabs.io/cli/sign-in.md)).
* A Reliant project and a connected machine that holds it ([Run a machine from the terminal](https://docs.reliantlabs.io/cli/run-a-machine.md)).
* On that machine: whatever the server needs to start. This guide's server needs `python3`. A server published to npm or PyPI needs `npx` or `uvx`.

**1. Get an MCP server**

Any stdio or HTTP MCP server works. This one is enough to see the whole path: one tool, `ticket_status`, that looks up a ticket.

```python ~/mcp-servers/tickets_mcp.py theme={null}
#!/usr/bin/env python3
"""A tiny MCP server over stdio: one tool, ticket_status."""
import json
import sys

TICKETS = {"OPS-101": "blocked: waiting on a database migration review",
           "OPS-102": "done: shipped in release v3.4.1"}

TOOL = {
    "name": "ticket_status",
    "description": "Look up the status of an OPS ticket by its id, e.g. OPS-101.",
    "inputSchema": {"type": "object",
                    "properties": {"id": {"type": "string"}},
                    "required": ["id"]},
}


def handle(method, params):
    if method == "initialize":
        return {"protocolVersion": params.get("protocolVersion", "2024-11-05"),
                "capabilities": {"tools": {}},
                "serverInfo": {"name": "tickets", "version": "0.1.0"}}
    if method == "tools/list":
        return {"tools": [TOOL]}
    if method == "tools/call":
        ticket = params.get("arguments", {}).get("id", "")
        text = TICKETS.get(ticket, f"no ticket named {ticket}")
        return {"content": [{"type": "text", "text": f"{ticket}: {text}"}]}
    if method == "ping":
        return {}
    raise KeyError(method)


for line in sys.stdin:
    msg = json.loads(line)
    if "id" not in msg:  # a notification, such as notifications/initialized
        continue
    reply = {"jsonrpc": "2.0", "id": msg["id"]}
    try:
        reply["result"] = handle(msg["method"], msg.get("params") or {})
    except KeyError:
        reply["error"] = {"code": -32601, "message": f"unknown method {msg['method']}"}
    print(json.dumps(reply), flush=True)
```

Check it answers before you wire it up:

```bash terminal theme={null}
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ticket_status","arguments":{"id":"OPS-101"}}}' \
  | python3 ~/mcp-servers/tickets_mcp.py
```

```text theme={null}
{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "OPS-101: blocked: waiting on a database migration review"}]}}
```

**2. Add it to the project**

Add the server to the project's `.reliant/mcp.json`, or use **Settings → MCP Servers → Add Custom** and choose the **Project** scope, which writes the same file:

```json .reliant/mcp.json theme={null}
{
  "mcpServers": {
    "tickets": {
      "command": "python3",
      "args": ["${HOME}/mcp-servers/tickets_mcp.py"]
    }
  }
}
```

The daemon on the chat's machine starts the server, so the command and path must exist on that machine. Use an absolute path or an environment reference such as `${HOME}`. Use **Project Local** (`.reliant.local/mcp.json`, gitignored) for a server only you use, and **Global** (`~/.reliant/mcp.json`) for every project on the machine.

**3. Check that it connected**

**Settings → MCP Servers** shows the server with its status and last error. On the machine, the daemon log records the handshake. Run this from the folder the machine's daemon serves, since `reliant daemon logs` picks the daemon by the current directory:

```bash terminal theme={null}
reliant daemon logs -n 2000 --follow=false | grep 'name=tickets'
```

```text theme={null}
level=INFO msg="Adding MCP server" name=tickets type=stdio …
level=INFO msg="MCP server connected" name=tickets server=tickets version=unknown hasTools=true …
```

Each of the server's tools reaches agents as `mcp__<server>__<tool>`, here `mcp__tickets__ticket_status`.

**4. Hand the tool to an agent with a preset**

A preset decides which tools an agent starts with. This one gives the ticket tools and read-only file access, and nothing that edits files:

```yaml .reliant/presets/ticket-desk.yaml theme={null}
name: ticket-desk
description: Answers questions about OPS tickets with the tickets MCP server
tag: agent
params:
  tools:
    - view
    - mcp__tickets__*
  system_prompt: |
    You answer questions about OPS tickets. Look each ticket up with the
    ticket_status tool; never guess a status.
```

`mcp__tickets__*` takes every tool the server has. Name one tool to take just that one, `!mcp__tickets__<tool>` removes one, and `tag:mcp` takes the tools of every connected server ([Presets](https://docs.reliantlabs.io/workflows/presets.md)).

**5. Use the preset in a workflow node**

```yaml .reliant/workflows/ticket-report.yaml theme={null}
name: ticket-report
description: An agent reports on OPS tickets using the tickets MCP server.

entry: [report]

nodes:
  - id: report
    type: workflow
    ref: builtin://agent
    presets:
      default: ticket-desk
```

`validate-tree` loads the project's presets too, so a misspelled preset name fails here rather than at run time:

```bash terminal theme={null}
reliant workflow validate-tree .reliant/workflows/ticket-report.yaml
```

```text theme={null}
  ✓ ticket-report.yaml (ticket-report)
✅ All workflows valid
```

**6. Run it and verify the agent called the tool**

Commit the three files so the machine syncs them, then run the workflow:

```bash terminal theme={null}
reliant workflow run ticket-report --project-path . \
  --message "What is the status of OPS-101 and OPS-102? One line each." --follow
```

```text theme={null}
Workflow "ticket-report" triggered
  Chat/Execution ID: 5ab752d2-7057-4c58-9eca-dd2f6dd6bc53
…
{"event":"workflow_completed",…,"workflow_name":"ticket-report",…}
```

Open the run under **Workflows → Runs**. The agent called the tool once per ticket and answered from the results:

```text theme={null}
mcp__tickets__ticket_status {"id": "OPS-101"}  →  OPS-101: blocked: waiting on a database migration review
mcp__tickets__ticket_status {"id": "OPS-102"}  →  OPS-102: done: shipped in release v3.4.1
- OPS-101: Blocked. It's waiting on a database migration review.
- OPS-102: Done. It shipped in release v3.4.1.
```

**7. Remove the server**

Remove it in **Settings → MCP Servers**, or delete its entry from `.reliant/mcp.json` and commit. Agents stop being offered its tools once the machine has synced the change.

## What this does not do

* **It needs a machine.** A chat or automation with no machine cannot reach a server that runs on one ([Which machine a chat runs on](https://docs.reliantlabs.io/machines/overview.md#which-machine-a-chat-runs-on)).
* **It does not vet the server.** The server runs as your user on that machine, with access to whatever it can read. Use servers you trust, and keep secrets in environment variables, not in `mcp.json` ([Security considerations](https://docs.reliantlabs.io/settings/mcp-servers.md#security-considerations)).
* **Calls follow the agent's mode.** In `manual` mode each MCP tool call asks for your approval, like a shell command; in `auto` mode it runs.

## Troubleshooting

> [accordion] MCP server "tickets" exited before completing the handshake
>
> The command started and exited before it answered. Run it by hand on the machine, as in the first step. A relative path is not resolved from your project, so use an absolute path or `${HOME}`, and check that `python3`, `npx` or `uvx` is installed there.

> [accordion] MCP tool 'mcp\_\_tickets\_\_ticket\_status' is not available in this environment
>
> The agent's tools name the server but it is not connected for this project. Check **Settings → MCP Servers**, and make sure the run's machine has synced your latest `mcp.json`: commit it, then choose **Restart** on the server in **Settings → MCP Servers**.

## Next steps

> [card] [MCP servers reference](https://docs.reliantlabs.io/settings/mcp-servers.md)
>
> Config scopes, variables, transports and security.

> [card] [Presets](https://docs.reliantlabs.io/workflows/presets.md)
>
> Tool lists, wildcards and exclusions for every agent.

> [card] [First multi-agent workflow](https://docs.reliantlabs.io/guides/workflows/first-multi-agent-workflow.md)
>
> Give each agent in a workflow its own tools.

> [card] [Call an API without exposing the key](https://docs.reliantlabs.io/guides/workflows/call-api-without-exposing-key.md)
>
> Reach a public API through a saved credential instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.