MCP Servers

MCP servers extend what your AI agents can do by connecting them to external tools and services through the Model Context Protocol. Configure MCP servers once, and every conversation in your project gains access to their tools automatically.

ReArch uses an MCP proxy that sits between your conversation containers and the upstream MCP servers. This means you manage all connections in one place, and agents receive a unified set of tools without needing per-container configuration.

How MCP Servers Work

When you add an MCP server to ReArch, the following happens:

1. The server configuration is stored in the database.
2. The MCP proxy detects the change and establishes a connection to the upstream server.
3. The proxy aggregates tools from all connected servers into a single tool catalog.
4. When a conversation container starts, it receives the proxy’s address and connects to it as a single MCP endpoint.
5. Agents inside the container can now call any tool from any connected MCP server.

Tool names are automatically prefixed with the server name to avoid collisions. For example, a tool called search on a server named brave-search becomes brave-search_search.

Server Types

ReArch supports two types of MCP servers:

Type	Transport	Use Case
Remote	Streamable HTTP or SSE	Cloud-hosted MCP services accessible via URL
Local	Stdio	Locally-run processes that communicate via standard input/output

Remote Servers

Remote servers connect to an MCP endpoint over HTTP. They are the most common type and are used for cloud-hosted integrations like GitHub, Sentry, Brave Search, and others.

• URL — The full endpoint URL of the MCP server (e.g., https://api.example.com/mcp).
• Headers — Optional HTTP headers sent with every request, typically used for authentication tokens.

Local Servers

Local servers run as child processes on the same host as the MCP proxy. They communicate over standard input/output (stdio) and are useful for tools that need local filesystem access or custom scripts.

• Command — The command and arguments to start the process. Each argument is specified on a separate line in the UI (e.g., npx, -y, @modelcontextprotocol/server-filesystem).
• Environment Variables — Key-value pairs passed as environment variables to the child process.

Adding MCP Servers

You can add MCP servers from the Administration > MCP Servers section. There are two ways to add a server: from the gallery or manually.

From the Gallery

The gallery provides a curated set of pre-configured MCP servers that you can add with minimal setup.

1. Navigate to Administration > MCP Servers.
2. Click Add Server.
3. Browse the available servers. Servers already installed in your project appear grayed out with a checkmark.
4. Click a server card to proceed to the configuration form, which will be pre-filled with the server’s details.
5. Adjust any settings as needed, such as adding authentication headers.
6. Click Save to create the server.

The gallery includes popular integrations:

Server	Description
Context7	Up-to-date documentation and code examples for LLMs
GitHub	Repository management, issues, pull requests, and code search
Sentry	Error tracking and performance monitoring
Brave Search	Web search powered by Brave
Linear	Issue tracking and project management
Figma	Design file access and inspection
Supabase	Database and backend management
Cloudflare	Workers, DNS, and infrastructure management
Browserbase	Cloud browser automation
Neon	Serverless Postgres management
Stripe	Payment processing and billing
Slack	Messaging and workspace management
Notion	Knowledge base and documentation
Vercel	Deployment and hosting management
Grep by Vercel	Regex search across GitHub repositories

Manual Configuration

For servers not included in the gallery, or for local servers, use manual configuration.

1. Navigate to Administration > MCP Servers.
2. Click Add Server, then click Configure Manually.
3. Fill in the required fields:
   • Name — A unique identifier using only letters, numbers, hyphens, and underscores (1-50 characters). This name is used as the tool prefix and cannot be changed after creation.
   • Type — Select Remote or Local.
   • URL (Remote only) — The MCP server endpoint URL.
   • Command (Local only) — The command to execute, with each argument on a separate line.
   • Headers (Remote only) — A JSON object of HTTP headers (e.g., {"Authorization": "Bearer token123"}).
   • Environment Variables (Local only) — A JSON object of environment variables (e.g., {"API_KEY": "abc123"}).
   • Enabled — Toggle whether the server should be active.
4. Click Save to create the server.

Configuring MCP Servers

Once a server is created, you can modify its settings at any time.

Editing a Server

1. Navigate to Administration > MCP Servers.
2. Click the Edit button on the server you want to modify.
3. Update any fields as needed. The server name cannot be changed.
4. Click Save to apply changes.

Changes are picked up by the MCP proxy automatically. The proxy detects configuration changes via database change streams in real time, or through polling every 30 seconds as a fallback.

Enabling and Disabling Servers

Each server has an Enabled toggle. Disabled servers are not loaded by the MCP proxy, and their tools are not available to agents. This is useful for temporarily removing access to a set of tools without deleting the server configuration.

Deleting a Server

1. Navigate to Administration > MCP Servers.
2. Click the Delete button on the server you want to remove.
3. Confirm the deletion in the dialog.

The proxy will disconnect from the upstream server and remove its tools from the catalog.

MCP Proxy

The MCP proxy is a standalone service that manages all upstream MCP server connections and exposes them as a single unified endpoint to conversation containers.

How the Proxy Works

• Tool aggregation — The proxy collects tools from all connected upstream servers and presents them as a single tool catalog. Each tool is prefixed with its server name to avoid naming conflicts.
• Request routing — When an agent calls a tool, the proxy strips the server name prefix and forwards the request to the correct upstream server.
• Hot reloading — When MCP server configurations change in the database, the proxy detects the change and reconnects only the affected servers. Unchanged connections are preserved.
• Batch support — The proxy supports batched JSON-RPC 2.0 requests for efficient tool calls.

Proxy Status

The MCP Servers administration page displays a status indicator showing whether the proxy is connected and how many upstream servers are active. You can also click Reload Proxy to force the proxy to re-read all server configurations from the database.

Authentication

The proxy supports optional authentication via a shared secret. When MCP_PROXY_SECRET is configured, all requests to the proxy must include the X-MCP-Secret header. The health check endpoint is always unauthenticated.

If MCP_PROXY_SECRET is not set, the proxy accepts all requests. This is suitable for development environments but should not be used in production.

Configuration Reference

The MCP proxy is configured through environment variables:

Variable	Default	Description
MCP_PROXY_PORT	3100	Port the proxy HTTP server listens on
MCP_PROXY_SECRET	(unset)	Shared secret for request authentication. When unset, all requests are allowed
MONGODB_URI	mongodb://localhost:27017/rearch	MongoDB connection string used by the proxy to read server configurations

The backend service uses additional variables to communicate with the proxy:

Variable	Default	Description
MCP_PROXY_URL	http://mcp-proxy:3100	URL the backend uses to reach the proxy for health checks and reload commands

Server Name Conventions

Server names serve as unique identifiers and tool prefixes throughout the system. When choosing a name:

• Use only letters, numbers, hyphens (-), and underscores (_).
• Keep it short and descriptive (1-50 characters).
• The name is immutable after creation and cannot be modified.
• The name is used as the prefix for all tools from that server (e.g., github_create_issue).

Access Control

MCP server management is restricted to users with the Admin role. Only administrators can create, edit, delete, or view MCP server configurations. All agents across the project share the same set of MCP tools defined by the enabled servers.