# How to Set Up External MCP Plugins in Reasonix: A Complete Configuration Guide

> Easily set up external MCP plugins in Reasonix. This guide details configuring `reasonix.toml` for stdio/HTTP transports, featuring auto-discovery and no per-tool auth.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: how-to-guide
- Published: 2026-08-05

---

**Configure external MCP plugins in Reasonix by declaring `[[plugins]]` tables in your [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) file, supporting both stdio and HTTP transports with automatic tool discovery and no per-tool authorization required.**

Reasonix exposes every external tool that follows the **MCP (Model-Client-Protocol)** specification as a plugin. These plugins are declared in TOML configuration files and become immediately available to the model without additional approval steps. Understanding how to set up external MCP plugins in Reasonix lets you extend the system's capabilities with third-party services, local executables, or custom tool servers.

## Where to Place Your Plugin Configuration

Reasonix follows a layered configuration hierarchy. When setting up MCP plugins, you can choose the appropriate scope for your needs:

1. **Command-line flags** — highest priority, overrides everything
2. **Project file** [`./reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/./reasonix.toml) — per-project plugin definitions
3. **User-level file** `~/.reasonix/config.toml` — global personal plugins
4. **Built-in defaults** — fallback configuration

For most use cases, add your `[[plugins]]` entries to the project-level [`./reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/./reasonix.toml) so team members share the same toolset. Personal plugins that shouldn't be committed to version control belong in `~/.reasonix/config.toml`.

## The `[[plugins]]` Table Schema

Each plugin requires a `[[plugins]]` table in your TOML file. The schema is defined in [`reasonix.example.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.example.toml) at lines 168-176 and documented in `site/src/pages/docs.astro` at lines 14-16.

### Required and Optional Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Logical identifier used in tool calls (`mcp__<name>__<tool>`) |
| `command` | For `stdio` | Executable that launches the local MCP server |
| `type` | No | Transport kind: `stdio` (default) or `http` |
| `url` | For `http` | Base URL of the Streamable HTTP server |
| `headers` | No | Static HTTP headers with environment variable expansion |
| `startup_timeout_seconds` | No | Seconds to wait for plugin initialization |
| `call_timeout_seconds` | No | Seconds allowed for a single tool call |
| `tool_timeout_seconds` | No | Per-tool timeout overrides as a table |

## Setting Up a Local stdio Plugin

stdio plugins spawn a local executable and communicate over standard input/output. This is the default transport type.

```toml

# ./reasonix.toml – local executable plugin

[[plugins]]
name    = "filesystem"
command = "reasonix-plugin-filesystem"

# Optional timeout configurations

startup_timeout_seconds = 60
call_timeout_seconds    = 300
tool_timeout_seconds    = { "search_large_directory" = 600 }

```

When a Reasonix session starts, the `command` executable is launched automatically. The model accesses tools using the naming convention `mcp__filesystem__<tool_name>`.

## Setting Up a Remote HTTP Plugin

HTTP plugins connect to existing MCP servers running as web services. Set `type = "http"` and provide the `url`.

```toml

# ./reasonix.toml – remote HTTP-based plugin

[[plugins]]
name    = "stripe"
type    = "http"
url     = "https://mcp.stripe.com"

# Headers support environment variable expansion with $VAR syntax

headers = { Authorization = "Bearer $STRIPE_KEY" }

# Optional timeouts

startup_timeout_seconds = 30
call_timeout_seconds    = 300

```

The `headers` field accepts any static key-value pairs and expands `$VARIABLE` syntax from your environment. This lets you inject API keys without hardcoding secrets.

## Per-Tool Timeout Overrides

Some MCP servers expose tools with vastly different execution characteristics. Use `tool_timeout_seconds` to override individual tool limits:

```toml
[[plugins]]
name                  = "video_generator"
command               = "reasonix-plugin-video"
call_timeout_seconds  = 60  # default for most tools

tool_timeout_seconds  = { "generate_video" = 1800, "render_preview" = 300 }

```

This configures `generate_video` for 30 minutes while keeping `render_preview` at 5 minutes and all other tools at 60 seconds.

## Discovery and Authorization Behavior

Once you set up external MCP plugins in Reasonix and restart your session, the following behaviors apply:

- **Automatic activation** — enabled plugins launch or connect when the session starts
- **Tool naming** — access tools as `mcp__<plugin_name>__<tool_name>`
- **Prompt commands** — MCP prompts become slash commands like `/mcp__stripe__create_invoice`
- **No per-tool approvals** — declaring a plugin in configuration constitutes full authorization

The installation of an MCP server is the **authorization decision**. Unless global deny rules intervene, all tools from a declared plugin are immediately usable.

## Verifying Your Plugin Setup

After editing your TOML file and starting a new session, confirm plugins are active:

```bash
/mcp              # Opens the MCP panel (CLI) or desktop MCP view

```

Test tool invocation with the naming convention:

```

mcp__stripe__list_customers    # Calls list_customers on the stripe plugin

mcp__filesystem__read_file     # Calls read_file on the filesystem plugin

```

## Handling [`.mcp.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/.mcp.json) Compatibility

If your project already contains a [`.mcp.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/.mcp.json) file in the project root, Reasonix reads it automatically. In case of **name collisions**, explicit `[[plugins]]` entries in [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) take precedence over [`.mcp.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/.mcp.json) definitions. This lets you migrate gradually or override external configurations.

## Configuration File References

The following source files define and document the plugin system:

- **[`reasonix.example.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.example.toml)** (lines 168-176) — commented template showing all plugin options
- **`site/src/pages/docs.astro`** (lines 14-16) — documentation describing transport types and naming conventions
- **[`./reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/./reasonix.toml)** — your project-level configuration where plugins are declared

## Summary

- **Declare plugins** using `[[plugins]]` tables in [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) or `~/.reasonix/config.toml`
- **Choose transport**: `stdio` for local executables, `http` for remote servers
- **Name tools** with the pattern `mcp__<plugin_name>__<tool_name>`
- **Authorize once** — plugin declaration grants access to all its tools
- **Override timeouts** globally or per-tool with `tool_timeout_seconds`
- **Restart sessions** after configuration changes to activate new plugins

## Frequently Asked Questions

### What is MCP in the context of Reasonix?

MCP stands for **Model-Client-Protocol**, a specification that defines how AI systems communicate with external tools. In Reasonix, any tool server implementing MCP can be registered as a plugin, extending the model's capabilities with standardized tool discovery and invocation patterns.

### Can I use environment variables in plugin configuration?

Yes. The `headers` field and other string values support **environment variable expansion** using `$VARIABLE` syntax. For example, `headers = { Authorization = "Bearer $API_KEY" }` injects the `API_KEY` environment variable at runtime, keeping secrets out of committed configuration files.

### Do I need to restart Reasonix after adding a plugin?

**Yes.** Plugin discovery and activation happens at session startup. After editing your [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) file, start a new Reasonix session to load the configuration. Running `/mcp` in the CLI or opening the MCP panel in the desktop interface confirms successful activation.

### Can I restrict which tools from a plugin are available?

**Not at the plugin level.** Declaring a plugin in Reasonix configuration authorizes all its tools. To restrict access, apply **global deny rules** in your configuration or do not declare the plugin. There is no per-tool granularity in the current `[[plugins]]` schema.