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:
| State | Meaning |
|---|---|
aligned | The launcher, native transport, activation, and required policy match the current REA setup. |
stale | A registration exists but needs refresh, such as an old package version, disabled entry, missing timeout, or incomplete policy. |
unknown | The launcher exists but its identity or native transport cannot be verified safely. |
missing | No usable REA entry is present in the effective client configuration. |
invalid | The location, document, entry shape, or required settings cannot be read or parsed. |
manual | The 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
| Trigger | Consequence | Guard |
|---|---|---|
| A higher-priority layer still selects another launcher | The requested registration is rejected before publication | Re-read all layers and compare the effective launcher |
| Kilo's Git worktree boundary is missing or incomplete | Project settings are not written | Require verified Git metadata or use global scope |
| The selected client entry means remote or unknown transport | The existing settings remain unchanged | Apply the client-owned native connection profile |
| A client has conflicting or malformed environment fields | Policy parsing fails instead of silently changing the stored environment | Enforce one native environment shape per client |
| The target file changes during the transaction | The write stops instead of overwriting newer settings | Check file identity and content before publication |
| Readback does not prove the new effective registration | The original is restored when possible and the result is failed | Verify the published file and effective launcher |
| A client has no supported local configuration writer | Status is manual and no local file is changed | Use the client-specific manual setup path |
Key files
| File | Why to read it |
|---|---|
| src/…/mcpRegistration.ts | Shows the mcp add command boundary and report presentation. |
| src/…/McpRegistrationCatalog.ts | Defines the MCP registration catalog, aliases, scopes, and profile selection. |
| src/…/McpRegistrationLocations.ts | Shows common global and project location rules. |
| src/…/McpRegistrationKiloLocations.ts | Shows Kilo's layered locations and writable project selection. |
| src/…/McpRegistrationGit.ts | Shows the read-only Git worktree discovery used by Kilo project registration. |
| src/…/ClientConfigurationDocument.ts | Defines the supported configuration dialects and server-table model. |
| src/…/McpRegistrationConfiguration.ts | Shows layer reading, merge preparation, and effective launcher checks. |
| src/…/ClientRegistration.ts | Shows client-specific launcher and policy parsing and replacement. |
| src/…/ClientRegistrationConnection.ts | Shows native transport admission for a stored entry. |
| src/…/ClientRegistration.test.ts | Shows the preservation, normalization, and transport-admission contracts for client entries. |
| src/…/McpClientRegistration.ts | Shows per-client updates, backups, verification, and partial outcomes. |
| src/…/ClientConfigurationTransaction.ts | Shows serialization of concurrent writes to one configuration path. |
| src/…/ClientRegistrationStatus.ts | Shows status states and remediation decisions. |
| src/…/mcpRegistration.ts | Defines the command options and registration report contract. |