Introducing a new way to review your PRs.

Read the announcement

morluto / rea

Reverse engineer anything with agents, from app behavior down to native binaries.

View on GitHub

27 documents · Updated Nov 20, 2026

docs / mcp-client-registration

MCP client registration

MCP client registration connects the REA MCP server to supported agent clients by placing one canonical local launcher in the client settings that the client will load. It resolves the right client profile and settings scope, understands each client's file format and transport rules, updates only the selected registration, and reports whether the result is ready for use. This page is a child of Client configuration and setup and relates to the command-line interface and MCP server pages.

Registration flow

The registration flow turns a command such as rea mcp add into a verified client setting. Selection happens before any writer receives permission to change a file. The flow also keeps partial results so a caller can see which clients changed and which did not.

flowchart LR
    A[Client names or aliases] --> B[Resolve profile and locations]
    B --> C[Read configuration layers]
    C --> D[Admit stdio connection]
    D --> E[Merge the REA entry]
    E --> F[Publish and verify]
    F --> G[Report each client]

The command accepts an optional client selection, a project-only switch, and a stdio command. It does not fetch a package or start an MCP server. The launcher is treated as exact process data, so its executable and arguments remain separate through parsing and publication. References: src/…/mcpRegistration.ts• L86-132, src/…/mcpRegistration.ts• L254-291, src/…/mcpRegistration.ts• L4-23

Client profile resolution

A client profile is the named description of how one client stores and selects an MCP connection. It binds a client ID to its display name, settings format, global and project targets, and native rules for deciding whether a stored entry means local stdio. This keeps profile decisions tied to the client definition instead of guessing from visible field names.

Selection accepts catalog IDs and documented aliases. An explicit selection resolves every requested target before writing starts. With no selection, registration discovers present global client locations and also includes the global-only Amp target. Project-only mode rejects global-only targets and requires a project location for every selected client. References: src/…/McpRegistrationCatalog.ts• L105-334, src/…/McpRegistrationCatalog.ts• L338-421, src/…/McpRegistrationCatalog.ts• L541-620

Configuration layers

Configuration layers are the ordered sources that a client reads to build one effective MCP entry. Registration reads those sources in native precedence order, changes only the selected writable layer, and checks the result again against the full effective view. A higher-priority source therefore cannot silently replace the launcher that the command requested.

The layer model supports global files, project files, client-specific fallback files, and selected inline configuration. A missing layer remains an empty position so later sources keep their native order. Read-only layers can supply inherited settings but do not grant write authority. References: src/…/McpRegistrationConfiguration.ts• L28-104, src/…/McpRegistrationConfiguration.ts• L107-178, src/…/ClientConfigurationFiles.ts• L112-165, src/…/ClientConfigurationFiles.ts• L218-281

Configuration formats

The registration system presents one MCP entry while preserving the format that the client already uses. JSON and JSONC clients use an mcpServers-style table in most cases. TOML clients use mcp_servers. Other clients use native tables or wrappers such as mcp, servers, context_servers, extensions, or amp.mcpServers.

The writer preserves unrelated settings and applies format-specific launcher shapes. Some clients store command and args, some store one command array, and Goose uses cmd with args. Goose also has one canonical environment field, while other clients keep their own environment field. OpenCode preserves environment keys and rejects malformed environment values. OpenCode can use a legacy table or a native nested table. A registration can migrate the entry to the effective native dialect while preserving client policy and activation data. References: src/…/ClientConfigurationDocument.ts• L39-82, src/…/ClientConfigurationDocument.ts• L114-137, src/…/ClientConfigurationDocument.ts• L287-398, src/…/ClientRegistration.ts• L108-137, src/…/ClientRegistration.ts• L290-395, src/…/ClientRegistration.test.ts• L41-66, src/…/ClientRegistration.test.ts• L96-236

Configuration locations

A configuration location is the path a client loads at a given scope. Location resolution uses the caller's home directory, working directory, platform, and relevant client settings. Environment overrides can select a different client home or file, while project locations are resolved from the current working directory.

The catalog covers both common fixed locations and clients with special location rules. Kilo can use global files, project files, directory layers, and an inline KILO_CONFIG_CONTENT source. ZCode can fall back to a shared user file when its native file has no server. Some clients have no writable local store and require manual configuration. References: src/…/McpRegistrationLocations.ts• L11-109, src/…/McpRegistrationLocations.ts• L111-219, src/…/McpRegistrationCatalog.ts• L105-334, src/…/SupportedClients.ts• L582-1049, src/…/ClientConfigurationFiles.ts• L284-340

Git project sources

Git metadata defines Kilo's project boundary when registration is project-scoped. The system observes the nearest repository boundary, the worktree root, the common Git directory, and the primary worktree. It uses these facts to identify project files that Kilo can write and to keep global or primary-worktree files read-only.

Git discovery is read-only. If the worktree boundary, repository paths, or worktree list cannot be verified, project registration stops before a settings file is changed. The caller can repair Git access or choose global registration instead. References: src/…/McpRegistrationGit.ts• L23-33, src/…/McpRegistrationGit.ts• L106-160, src/…/McpRegistrationGit.ts• L162-219, src/…/McpRegistrationGit.ts• L221-271, src/…/McpRegistrationKiloLocations.ts• L200-294

Connection settings

Connection settings describe how the client reaches the REA server. Registration owns the local stdio launcher and the native fields that could select a different transport, but it does not own unrelated client policy. Before writing, it proves that the effective entry selects the requested stdio connection.

The native profile can require or reject fields such as type, transport, url, serverUrl, or uri. Nested clients such as Cline keep the transport object in its native place. The launcher parser can retain command data even when the native transport is remote or the stored arguments are malformed, but connection admission still rejects that entry as not ready for local launch. Remote HTTP or SSE selections are not converted into local stdio by accident. If the existing entry does not establish a safe stdio meaning, registration reports an unknown or invalid connection and leaves the settings unchanged. References: src/…/ClientRegistrationProfile.ts• L3-52, src/…/ClientRegistrationSource.ts• L4-24, src/…/ClientRegistrationConnection.ts• L20-160, src/…/ClientRegistration.test.ts• L238-285

Launcher and policy values

The launcher is the process identity that starts the MCP server. Client policy remains alongside it, including environment values, activation flags, tool selections, and client-specific timeout settings. Registration replaces connection fields while retaining compatible policy and inherited values.

Nested clients use the selected native launcher when policy is read. For example, Cline's transport entry supplies the command and arguments even if shadow fields exist elsewhere. Registration also keeps client metadata and activation values while it replaces the launcher. Status checks separate launcher identity from readiness policy. This lets the system report a usable launcher as stale when a timeout, package version, tool selection, or activation setting needs attention. It also avoids exposing stored environment values in status output. References: src/…/ClientRegistration.ts• L163-220, src/…/ClientRegistration.ts• L397-480, src/…/ClientRegistrationStatus.ts• L58-95, src/…/ClientRegistrationStatus.ts• L286-447, src/…/ClientRegistration.test.ts• L68-94, src/…/ClientRegistration.test.ts• L287-307

Transactional updates

A registration update is a read, merge, publish, and verify transaction for one resolved settings path. The operation takes a snapshot before editing and checks that the selected file is still the same file before publication. Existing content receives a backup before it is replaced.

The update publishes staged bytes and then reads the file back. It verifies both the file identity and the effective REA launcher. If verification fails, it attempts to restore the original content. Concurrent updates to the same path wait in order, while updates to different paths can proceed independently. References: src/…/McpClientRegistration.ts• L107-220, src/…/McpClientRegistration.ts• L256-339, src/…/ClientConfigurationTransaction.ts• L3-27, src/…/ClientConfigurationPublication.ts• L63-188

Private profiles apply stronger local file modes where the client requires them. POSIX mode changes are verified. Windows reports the requested modes but does not claim that ACL privacy was verified. Cleanup failures remain attached to the registration result so a failed resource close cannot be mistaken for a successful update. References: src/…/McpClientRegistration.ts• L167-200, src/…/McpClientRegistration.ts• L342-425, src/…/ClientConfigurationPublication.ts• L242-275

Registration status

Registration status is a read-only view of whether each detected or explicitly selected client can use the current REA entry. It reads the effective configuration, checks the native transport and launcher identity, evaluates activation and policy, and returns a remediation message when the registration needs action.

The main states have distinct meanings:

StateMeaning
alignedThe launcher, native transport, activation, and required policy match the current REA setup.
staleA registration exists but needs refresh, such as an old package version, disabled entry, missing timeout, or incomplete policy.
unknownThe launcher exists but its identity or native transport cannot be verified safely.
missingNo usable REA entry is present in the effective client configuration.
invalidThe location, document, entry shape, or required settings cannot be read or parsed.
manualThe client has no supported local writer and needs configuration outside this system.

Automatic discovery uses product evidence before reading a client. Explicit selection authorizes inspection even when a location is hard to probe. Shared files are handled with care because their presence can belong to another product; a recognizable REA entry can prove registration ownership without proving that every product using the file is installed. References: src/…/ClientRegistrationStatus.ts• L128-231, src/…/ClientRegistrationStatus.ts• L257-337, src/…/ClientRegistrationStatus.ts• L372-467, src/…/ClientRegistrationStatus.ts• L649-693, src/…/SupportedClients.ts• L1067-1126

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep each catalog client's scope, location resolver, format, native connection profile, and alias mapping aligned.
  • Keep every layered client's read order aligned with its writable target and effective merge rules.
  • Keep launcher serialization aligned with native connection admission for flat and nested client entries.
  • Keep environment aliases and nested launcher selection aligned with the policy parser for each client dialect.
  • Keep status alignment rules aligned with setup refresh rules so a reported remediation can actually repair the state.
  • Keep Kilo Git boundary checks aligned with the project files that receive write authority.
  • Keep the registration report schema aligned with partial completion, backup paths, permission results, and failure states.

Important failure modes

TriggerConsequenceGuard
A higher-priority layer still selects another launcherThe requested registration is rejected before publicationRe-read all layers and compare the effective launcher
Kilo's Git worktree boundary is missing or incompleteProject settings are not writtenRequire verified Git metadata or use global scope
The selected client entry means remote or unknown transportThe existing settings remain unchangedApply the client-owned native connection profile
A client has conflicting or malformed environment fieldsPolicy parsing fails instead of silently changing the stored environmentEnforce one native environment shape per client
The target file changes during the transactionThe write stops instead of overwriting newer settingsCheck file identity and content before publication
Readback does not prove the new effective registrationThe original is restored when possible and the result is failedVerify the published file and effective launcher
A client has no supported local configuration writerStatus is manual and no local file is changedUse the client-specific manual setup path

Key files

FileWhy to read it
src/…/mcpRegistration.tsShows the mcp add command boundary and report presentation.
src/…/McpRegistrationCatalog.tsDefines the MCP registration catalog, aliases, scopes, and profile selection.
src/…/McpRegistrationLocations.tsShows common global and project location rules.
src/…/McpRegistrationKiloLocations.tsShows Kilo's layered locations and writable project selection.
src/…/McpRegistrationGit.tsShows the read-only Git worktree discovery used by Kilo project registration.
src/…/ClientConfigurationDocument.tsDefines the supported configuration dialects and server-table model.
src/…/McpRegistrationConfiguration.tsShows layer reading, merge preparation, and effective launcher checks.
src/…/ClientRegistration.tsShows client-specific launcher and policy parsing and replacement.
src/…/ClientRegistrationConnection.tsShows native transport admission for a stored entry.
src/…/ClientRegistration.test.tsShows the preservation, normalization, and transport-admission contracts for client entries.
src/…/McpClientRegistration.tsShows per-client updates, backups, verification, and partial outcomes.
src/…/ClientConfigurationTransaction.tsShows serialization of concurrent writes to one configuration path.
src/…/ClientRegistrationStatus.tsShows status states and remediation decisions.
src/…/mcpRegistration.tsDefines the command options and registration report contract.