Skip to content
Raw

MCP servers

Raw can use tools from Model Context Protocol servers. You define each server once in your config file. An agent then selects the individual tools it needs.

Define servers

Section titled “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 
{
  "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

Section titled “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.

What the model receives

Section titled “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

Section titled “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.

"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 describes the panel format.

Use a server from a package

Section titled “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.

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

The agent then selects mcp/web/query. See Packages.

Set up a server

Section titled “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.

Section titled “Related”