# MCP servers

> Define Model Context Protocol servers in your Raw config, then select individual tools for an agent over stdio or Streamable HTTP.

Raw can use tools from [Model Context Protocol](https://modelcontextprotocol.io/) servers. You define each server once in your config file. An agent then selects the individual tools it needs.

## Define servers

Servers live in the `mcp.servers` section of the same config file as your models and agents. Raw supports two transports.

| Transport         | Required fields | Optional fields |
| ----------------- | --------------- | --------------- |
| `stdio`           | `command`       | `args`, `env`   |
| `streamable-http` | `url`           | `headers`       |

```json
{
  "default_agent": "research",
  "models": {
    "local": {
      "provider": "ollama",
      "method": "openai-chat-completions",
      "model_id": "YOUR_INSTALLED_MODEL"
    }
  },
  "mcp": {
    "servers": {
      "search": {
        "transport": "stdio",
        "command": "my-search-server",
        "args": [],
        "env": {}
      },
      "vision": {
        "transport": "streamable-http",
        "url": "https://example.test/mcp",
        "headers": {}
      }
    }
  },
  "agents": {
    "research": {
      "model": "local",
      "tools": {
        "use": [
          "builtin/read_file",
          "mcp/search/web_search",
          "mcp/vision/describe"
        ]
      }
    }
  }
}
```

A server definition does nothing until an agent selects one of its tools. Raw does not start unselected servers, and it does not add their tools to the model’s context.

## Select tools

Select each tool by its original name with `mcp/<server>/<tool>` in `tools.use`. The wildcard `*` is not accepted as a selection. An unknown server or tool name fails before any model request is sent.

Policy rules match the same identity. For example, `mcp/search/*` is a valid `match` in `tools.rules`. See [Tools](https://raw.tlelabs.com/docs/extend/tools/#control-tools-with-rules).

## What the model receives

- Text and JSON results come back as typed results.
- Image blocks are passed to models that accept them. A text-only model can instead call a vision server that returns a text description.
- Raw does not fetch URLs that a tool returns as resource links. It reports them as links.
- MCP tools do not receive variable references or interpolation in their `env` or `headers`. The values you write are used literally.

Raw applies the request timeout to MCP calls and closes its MCP clients when a session ends. Any server process Raw started is stopped at the same time.

## Add panels to a server tool

A tool can show a live side panel. For an MCP tool, you declare the panel in the server definition. The `tool` field is the tool’s original name on the server.

```json
"search": {
  "transport": "stdio",
  "command": "my-search-server",
  "panels": [{ "tool": "web_search", "id": "results", "title": "Results" }]
}
```

Each tool can declare up to four panels. A server can also send panel updates in its tool results without a declaration. The [Tool contract](https://raw.tlelabs.com/docs/reference/tool-contract/) describes the panel format.

## Use a server from a package

A package can export an MCP server definition. You bind it to a local name in your config, and the local name is what you select in `tools.use`.

```json
"mcp": {
  "servers": {
    "web": {
      "from": "pkg/kit/mcp/search",
      "inputs": { "endpoint": "https://recipient.example/mcp" }
    }
  }
}
```

The agent then selects `mcp/web/query`. See [Packages](https://raw.tlelabs.com/docs/extend/packages/).

## Set up a server

1. Install the server software and confirm its command runs on your machine.

2. Add the server under `mcp.servers` in your config file. Use the server’s own credentials in `env` or `headers`. Those values are stored in the config file as written.

3. Select the tools you want in an agent’s `tools.use`.

4. Run a request that needs the tool. Check the result, because a successful config check does not prove the server works.

> **Caution:**
>
> The server runs with your user permissions and uses its own credentials. Raw passes its results to the model. Select only the tools you trust.

## Related

- [Tools](https://raw.tlelabs.com/docs/extend/tools/) covers the built-in tools and the tool selection rules.
- [Configuration reference](https://raw.tlelabs.com/docs/reference/configuration/) lists every config field.