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

Configure external MCP plugins in Reasonix by declaring [[plugins]] tables in your 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 — 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 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 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.

# ./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.

# ./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:

[[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:

/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 Compatibility

If your project already contains a .mcp.json file in the project root, Reasonix reads it automatically. In case of name collisions, explicit [[plugins]] entries in reasonix.toml take precedence over .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 (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 — your project-level configuration where plugins are declared

Summary

• Declare plugins using [[plugins]] tables in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}