MCP tool registration
MCP tool registration turns REA product operations into one discoverable server surface for MCP clients. It groups tools by user capability, gives each tool a shared contract, and connects each contract to the analysis or session service that can fulfill it.
Registration model
Server assembly
The server assembly creates the MCP server, prepares the services that support optional capabilities, and invokes the registration modules. A session source adds target lifecycle and evidence tools; a fixed analysis source keeps the server useful for direct analysis without session state. Advertised tool families and provider availability control which capabilities appear and which optional providers can be used at call time.
The registration modules receive a common server context. This context carries the active target, evidence access, logging, analysis admission, provider services, and the set of advertised families. This keeps product operations separate from the MCP transport while still giving each tool the state it needs.
flowchart TD
S[Server source] --> A[Server assembly]
A --> C[Shared server context]
C --> R[Capability registration modules]
R --> T[Registered MCP tools]
T --> M[MCP client]
C --> P[Analysis and provider services]
T --> P
C --> V[Capability and provider availability]
V --> T
References: src/…/createServer.ts• L280-341 src/…/createServer.ts• L409-438 src/…/createServer.ts• L809-862 src/…/registerSessionStatusTool.ts• L98-187
Capability modules
Each registration module represents a product capability rather than a transport concern. The module selects the contracts it owns and maps them to the service or workflow that provides the capability. Recent groups also keep provider-specific tools visible when the provider is optional, then report provider availability when a caller uses the tool.
| Capability group | Product purpose |
|---|---|
| Analysis settings | Inspect or update runtime analysis choices without an active target. |
| Official analysis | Direct analysis operations exposed as named product actions. |
| Enhanced analysis | Composed workflows that answer higher-level investigation questions. |
| Evidence providers | Native, artifact, managed-code, firmware, browser, runtime, Android, and other provider-backed observations. |
| Specialized inspections | Focused binary, package, database, packet, firmware, language-runtime, and model-artifact inspections that use the shared evidence path. |
| Application workflows | Provider-neutral application tracing, comparison, reconstruction, coverage, environment-bundle, graph, and guided-workflow operations. |
| Guidance access | Provider-free search and retrieval of the installed guide bundle. |
| Comparisons and investigation workflows | Cross-target comparisons and evidence-backed conclusions about changed behavior, call paths, runtime correlation, and reconstruction. |
| Session operations | Target selection, lifecycle, evidence bundles, unknowns, context, and process capture. |
| External analysis tools | Debuggers, instrumentation, browser automation, and other optional analysis engines. |
| Reverse-engineering tools | Objdump inspection and Rizin command execution against an analysis target. |
The contract inventory defines the public capability order. Optional providers can still register their public tools while reporting that a provider is unavailable when a caller invokes one. Runtime settings, guidance access, and provider-free guided workflow access remain available when no target or healthy provider exists.
Specialized modules bind named inspection contracts to their owning services. They do not create a separate public contract model. They reuse the shared evidence handler so their observations enter the same session evidence ledger as other provider results. This includes Android, native, managed, artifact, binary-diagnostic, language-runtime, WASM, and platform-specific inspections.
Application registration groups higher-level operations that work from existing evidence or application inputs. These tools trace features and JavaScript semantics, compare versions and source to bundles, compare export shapes, build reconstruction obligations, evaluate coverage, export environments, project mobile application graphs, and expose guidance and guided workflows. Shared application registration options provide artifact resources, logging, analysis admission, and optional evidence readers and writers so derived answers can stay linked to investigation records.
Persistent external tools need more than a single analysis call. Frida registration covers device discovery and instrumentation sessions. GDB and Rizin registration covers debugger sessions, commands, status, and cleanup. Reverse-engineering registration covers objdump and Rizin, including extra admission and cleanup rules for commands that can change the target.
References: src/…/toolContracts.ts• L47-94 src/…/registerAnalysisSettingsTools.ts• L8-32 src/…/registerApplicationTools.ts• L16-31 src/…/types.ts• L10-20 src/…/registerGuidanceTools.ts• L11-45 src/…/registerAndroidTools.ts• L17-132 src/…/registerManagedTools.ts• L13-60 src/…/registerNativeTools.ts• L7-12 src/…/registerOfficialTools.ts• L6-12 src/…/registerPrompts.ts• L24-57 src/…/registerGuidedWorkflowTool.ts• L7-19 src/…/registerReverseEngineeringTools.ts• L25-46 src/…/guidedWorkflowsTool.test.ts• L1-20
Artifact delivery
Artifact registration adapts the shared evidence flow for inspections that can return a retained summary. Delivery detail is a caller-facing choice, so it is removed before execution and evidence identity. Artifact extraction also receives a controlled output destination rather than a caller-selected execution path.
The same delivery choice applies to binary diagnostics, browser analysis, Electron analysis, BEAM and Python inspections, packet captures, WASM artifacts, and other focused inspections. WASM interface comparison and artifact inspection use the same evidence and delivery model. A summary is a view of retained evidence; it does not become a different analysis operation.
References: src/…/registerArtifactTools.ts• L8-19 src/…/registerBinaryDiagnosticsTools.ts• L17-75 src/…/registerByteEntropyTool.ts• L12-33 src/…/registerBrowserTools.ts• L80-109 src/…/registerElectronTools.ts• L93-129 src/…/registerErlangTools.ts• L11-33 src/…/registerPythonPycTool.ts• L11-33 src/…/registerWebNetworkCaptureTool.ts• L16-64 src/…/registerPcapTools.ts• L17-51 src/…/registerWasmTools.ts• L21-65
Shared registration contracts
Tool contract
A tool contract is the single public description of one MCP operation. It names the tool, states its purpose, defines input and output schemas, identifies its adapter family, records effects, marks target-derived content, and provides caller examples.
The contract inventory groups these descriptions into capability families and resolves a contract by its public name. Registration uses the same contract that catalog and verification tools use. This prevents the advertised tool surface from drifting away from the operation that handles the call.
Direct analysis contracts use the official contract family. Each contract has a strict input schema and a required output schema. The family includes read operations, navigation and metadata operations, and analyst edits that bridge directly to an analysis provider without extra application composition.
References: src/…/toolContractTypes.ts• L20-69 src/…/toolContracts.ts• L47-112 src/…/officialToolContracts.ts• L21-35 src/…/officialToolContracts.ts• L38-240
Contract binding registry
The contract binding registry maps each named public contract to the kind of product operation that can fulfill it. A binding can run an evidence operation, return a value, read admitted analysis, derive a result from session evidence, run an application workflow, call a provider operation, perform an external mutation, or retain a complete result behind a selected view.
The registry chooses the matching shared handler and registers the contract with the MCP server. It distinguishes SDK admission from application admission, so an application workflow can validate the raw request and shape its own input errors. It also rejects bindings for missing contracts and rejects provider bindings whose operation name does not match the contract. These checks keep the public contract list, execution path, and server surface joined at startup instead of relying on separate name-based wiring.
Provider bindings require analysis admission. A value binding can instead run without analysis for provider-free guidance, discovery, and status reads, while an explicitly admitted value binding uses the analysis gate. This lets the same registry express both lightweight server reads and analysis-backed operations.
References: src/…/contractToolBindings.ts• L83-219 src/…/contractToolBindings.ts• L238-368 src/…/contractToolBindings.ts• L389-408 src/…/contractToolBindings.ts• L499-668
Wire registration
The shared registration options project a contract into the MCP SDK. The projection preserves the public title, description, input schema, output schema, and execution hints. The server can change how schemas are presented to clients without changing the canonical parser or the product contract.
Input metadata gives clients usable property descriptions and examples. Output schemas can carry stable identities. Application workflows may accept raw input at the SDK boundary so they can return the same field-aware errors as the product service; their canonical contract still defines the advertised shape. Value tools can also apply a final presentation step when a response must hide caller-provided secrets or handles.
References: src/…/toolRegistrationOptions.ts• L8-40 src/…/toolSchemaMetadata.ts• L59-127 src/…/EvidenceMcpServer.ts• L134-178 src/…/contractToolBindings.ts• L153-160 src/…/environmentBundle.ts• L14-50
Effect and safety metadata
Each public tool has an explicit effect audit. The audit records whether an operation can change the target or session, write files, launch processes, use the network, change UI state, discard data, execute foreign code, or change an attached device. It also records whether the operation is idempotent.
MCP annotations are derived only from this effect metadata. The result marks a tool as read-only only when none of the audited effects apply. It marks destructive behavior for data loss, foreign-code execution, or device changes, and marks open-world behavior for process or network access.
Tools that can return target, provider, launcher, or device content also carry that fact into result delivery. Only a small audited set is content-free. Unknown tool names remain marked as content-producing until they are audited, which tells clients to treat strings, code, logs, captures, diagnostics, and file content as untrusted data rather than instructions.
The effect audit covers analysis settings, application workflows, guidance access, guided workflows, specialized inspections, browser tools, Android operations, and external-tool groups as well as core analysis tools. This makes a new registration module incomplete until its public names also have effect metadata and content-provenance behavior.
References: src/…/toolEffects.ts• L1-30 src/…/toolEffects.ts• L32-54 src/…/toolEffects.ts• L693-756 src/…/toolEffects.ts• L758-831
Product operation flow
Contract-backed execution
Most product operations follow one path from MCP request to an evidence-backed or value response. The contract binding registry selects the shared handler, which admits the operation when needed, validates the contract input, runs the product service with cancellation and progress, records evidence when the operation produces an observation, and converts the result into the contract output.
The exact path differs by capability. Direct analysis tools call a named analysis operation. Enhanced tools run a composed workflow. Provider-backed tools use the shared evidence registration path. Session tools call long-lived session services for lifecycle or investigation state. Application tools derive evidence from application inputs or earlier evidence. Query tools read the analysis granted to the call and return a value. Summary or selected-view requests change delivery after the complete result is retained; they do not change the product operation.
sequenceDiagram
participant Client as MCP client
participant Tool as Registered tool
participant Gate as Analysis admission
participant Service as Product operation
participant Ledger as Evidence or session record
Client->>Tool: Call with contract input
Tool->>Gate: Admit operation
Gate->>Service: Run with signal and progress
Service-->>Tool: Result or typed error
Tool->>Ledger: Record evidence or session change
Tool-->>Client: Contract-shaped result
Shared handlers also preserve partial evidence on some failures and use the tool's target-content flag when they encode errors. This gives clients a stable response shape while keeping the evidence record useful for later work.
References: src/…/contractToolHandler.ts• L15-91 src/…/contractToolBindings.ts• L547-652 src/…/providerOperationToolHandler.ts• L72-177 src/…/registerOfficialTools.ts• L6-12 src/…/registerEnhancedTools.ts• L236-359 src/…/compareSourceToBundle.ts• L23-123
Session-scoped operations
Session registration adds operations that need a long-lived investigation context. These tools open and close targets, report session status, manage evidence bundles and residual unknowns, provide analysis context, and run comparisons, derived investigations, or process captures.
The session is also the main place where tool results become durable investigation state. Process capture records typed evidence and turns residual gaps into unknowns for later work. Evidence bundle tools move that state across sessions, while unknown tools let clients list, add, update, and verify unresolved questions. Artifact comparisons and other derived investigations resolve retained evidence records, record those sources, and create derived records; a changed, truncated, or unknown result can also create a residual unknown with a recommended follow-up inspection. Session registration owns process-capture cleanup when the server closes, so temporary resources do not outlive the session.
References: src/…/registerSessionTools.ts• L46-149 src/…/registerSessionTools.ts• L299-456 src/…/registerSessionRecordTools.ts• L35-293 src/…/registerSessionStatusTool.ts• L98-187 src/…/registerArtifactComparisonTool.ts• L19-119 src/…/registerBundleComparisonTool.ts• L16-95 src/…/registerInvestigationTools.ts• L30-196 src/…/registerCloseLifecycleTool.ts• L30-126
Provider-backed observations
Provider-backed registration turns a family of analysis services into evidence-producing MCP tools. The shared provider handler performs input and delivery preflight, analysis admission, progress reporting, operation logging, source recording, evidence creation, evidence projection, and delivery handling without repeating the same policy for every provider.
The handler can reuse a matching completed observation already held by the session. Otherwise it admits a new analysis and records the completed operation as atomic Evidence. A summary request is checked before analysis; when a contract does not retain complete Evidence, the provider is not called.
Provider operation families can adjust how an admitted analysis reaches a service. Managed operations can use a selected managed file when a call omits its path. Artifact extraction receives a server-created output destination. These adapters keep provider-specific routing and resource limits outside the common evidence flow.
The Android, language, APK-signature, binary-diagnostic, and artifact registration modules use this path to keep product-specific services behind one public behavior. A provider result becomes an observation tied to the active target and session, while the operation name and execution parameters preserve how the observation was made.
Browser, Electron, and JavaScript runtime registration groups web observations behind the same result model. They report an unavailable optional provider at call time, apply analysis admission, carry cancellation and progress into the service, and deliver results as session evidence. Electron tools cover target and page inspection, application analysis, runtime reconciliation, active scenarios, and fuse inspection through this common surface. Local web-script export, application environment export, and other provider-free workflows remain usable without a live browser provider.
Some tools can return a retained summary instead of full detail. That choice affects delivery only; it does not change the analysis operation or the identity of the retained evidence.
References: src/…/providerOperationToolHandler.ts• L32-69 src/…/providerOperationToolHandler.ts• L71-177 src/…/providerOperationFamilies.ts• L12-75 src/…/registerAndroidTools.ts• L17-132 src/…/registerBinaryDiagnosticsTools.ts• L17-75 src/…/registerBrowserTools.ts• L36-183 src/…/registerElectronTools.ts• L49-194 src/…/registerJavaScriptRuntimeObservationTools.ts• L24-58 src/…/registerWebNetworkCaptureTool.ts• L16-64 src/…/registerArtifactTools.ts• L8-19 src/…/registerWasmTools.ts• L21-65
Application workflows
Application registration exposes higher-level questions through workflows that combine application records, retained evidence, and bounded analysis results. These operations support feature tracing, semantic tracing, version and source-to-bundle comparison, export-shape comparison, reconstruction obligations, coverage checks, environment export, and mobile application graph projection.
The workflows record source evidence before they return a derived result. A complete parent result is retained before a caller asks for a smaller view, so the view remains linked to its source. When a comparison or reconstruction result is incomplete, the registration path can add a residual unknown with a follow-up probe. Artifact comparison follows the same rule: it links the compared evidence, stores the derived result, and records an unresolved question when the result does not establish a complete answer.
References: src/…/registerApplicationTools.ts• L16-31 src/…/types.ts• L10-20 src/…/helpers.ts• L19-136 src/…/compareVersions.ts• L14-55 src/…/compareSourceToBundle.ts• L23-65 src/…/compareExportShapes.ts• L12-60 src/…/traceFeature.ts• L12-61 src/…/traceSemantics.ts• L12-55 src/…/projectMobileApplicationGraph.ts• L21-93 src/…/registerArtifactComparisonTool.ts• L38-118 src/…/registerBundleComparisonTool.ts• L44-91
Guided workflow access
Guided workflow access gives clients provider-free entry to the existing guided prompt contracts. It uses the server's advertised tool families so a workflow does not describe calls that are not available in the current server configuration.
The prompt registry uses the same family scope and can update prompt descriptions and argument completion as capabilities change. Guidance search and section retrieval provide direct access to the installed guide bundle without an analysis target; guided workflows use that product knowledge to help a client choose available operations.
References: src/…/registerGuidanceTools.ts• L11-45 src/…/registerGuidedWorkflowTool.ts• L7-19 src/…/registerPrompts.ts• L19-57 src/…/guidedWorkflowsTool.test.ts• L1-20
Composed investigation workflows
Enhanced registration exposes higher-level native analysis questions through workflows that combine lower-level analysis operations. The workflow runner admits the call, reports progress, records the result as typed evidence, and can retain a replayable snapshot or create unknowns when the result remains incomplete.
This keeps a composed answer in the investigation record instead of returning it as an isolated response. The analyze_function path uses the same evidence delivery goal while delegating its analysis-specific work to a dedicated operation.
References: src/…/registerEnhancedTools.ts• L69-230 src/…/registerEnhancedTools.ts• L236-359 src/…/registerEnhancedTools.ts• L361-474 src/…/registerManagedTools.ts• L13-60
Persistent tool sessions
Debugger and instrumentation groups expose stateful external tools whose operations span several MCP calls. A start operation creates a provider session, later calls address that session, and close operations retire it through the same result and cleanup model.
These tools need stronger safety handling because commands can mutate the target, launch processes, use the network, or execute foreign code. GDB, Rizin, and Cutter commands therefore use external-mutation admission, while Frida also preserves partial observations when a session operation fails after producing useful data.
References: src/…/registerFridaTools.ts• L38-285 src/…/registerGdbTools.ts• L42-153 src/…/registerRizinDebugTools.ts• L35-135 src/…/registerCutterTools.ts• L15-71 src/…/registerReverseEngineeringTools.ts• L25-181
Change checklist
When these files or sections are changed, remember to consider these:
- Add or remove a public operation in its capability contract family and its contract binding map. Keep any capability registration that supplies the binding aligned with both.
- Keep the contract's input and output schemas aligned with the handler's result and with any catalog or verification path that reads
TOOL_CONTRACTS. - Keep each binding's execution shape aligned with its handler. Keep provider operation names exact and keep application admission distinct from SDK admission.
- Recheck effect flags, target-content marking, and MCP annotations when an operation gains file, process, network, device, or target side effects.
- Preserve the distinction between delivery-only fields and analysis parameters when adding summary or compact response modes.
- When a session-only operation changes, check fixed-target registration paths so the tool is not exposed without the state it needs.
- When an optional provider changes, keep registration, availability reporting, and provider cleanup in agreement.
- When a specialized inspection is added, connect its named contract to the shared evidence handler and to the owning session evidence ledger.
- When application workflows change, keep source-evidence links, derived evidence identity, incomplete-result unknowns, and delivery projections aligned.
- When guidance or guided workflows change, keep guide access, prompt content, and advertised family scope aligned so clients do not receive unavailable operations.
- When browser, Electron, or runtime operations change, keep provider diagnostics, admission, progress, retained views, and evidence delivery aligned.
- When debugger or instrumentation support changes, keep session creation, command admission, partial evidence, and cleanup aligned.
- When reverse-engineering commands change, keep command parsing, external-mutation admission, snapshot invalidation, and retirement handling aligned.
- When a derived investigation workflow changes, keep its evidence links, derived evidence type, completeness checks, and recommended probes aligned.
- When a direct analysis operation changes, update its strict input schema, required output schema, effect audit, and provider adapter together.
- When a provider operation changes, keep preflight reuse, source-evidence recording, execution routing, and retained-result delivery aligned.
- When managed or artifact routing changes, keep selected-file fallback and server-owned extraction destinations outside the provider's analysis parameters.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A contract is absent from the family inventory or contract binding map | The operation is missing from the MCP surface or from catalog checks | Keep the family contract list and binding map aligned with TOOL_CONTRACTS. |
| Handler input or output changes without a contract change | Clients receive a schema that does not describe the real operation | Use the canonical contract for registration and delivery. |
| A binding selects the wrong execution shape or provider operation | A call reaches the wrong service or fails after registration | Use the binding type and startup checks to keep each contract matched to its handler and named operation. |
| A session-only tool is registered without a session | The tool cannot resolve target, evidence, or lifecycle state | Register session tools only when createServer has a session source. |
| An optional provider cannot load | Calls fail even though the tool is listed | Report the provider load failure at call time through the tool's normal result path. |
| A specialized inspection bypasses the shared provider handler | Its result can use different admission, logging, or evidence rules | Bind the service through the common provider evidence path unless it needs a documented stateful flow. |
| A delivery field reaches analysis or evidence identity | Equivalent observations split into different records or unsupported execution input is sent | Remove delivery-only fields before execution and evidence creation. |
| A summary request has no retained complete-result contract | The provider runs without a deliverable complete evidence record | Preflight delivery before analysis and refuse the request when retention is not available. |
| An application comparison skips source evidence or unknown registration | A derived result loses its audit trail or hides incomplete coverage | Record source evidence first and create a scoped unknown when the result is incomplete. |
| A persistent external command skips mutation admission | A command can change the target without the session policy or cleanup path | Keep GDB, Rizin, and Cutter command execution behind external-mutation admission. |
| A derived workflow uses evidence that is not in the session | The result cannot be linked to a durable investigation record | Resolve the evidence closure before creating workflow evidence. |
| A direct analysis tool lacks an effect audit | MCP safety hints and target-content handling can be wrong or registration can fail | Add the public name to TOOL_EFFECTS before creating its contract metadata. |
| Target-derived content is not marked as untrusted | A client may treat analysis data as instructions | Keep returnsTargetContent and result provenance aligned with the operation. |
| Guided workflow scope includes a disabled tool family | A client receives steps that it cannot execute | Build guided workflow access and prompt registration from the same advertised families. |
| Guidance tools are registered without the installed guide resource scope | Search or section reads cannot resolve the guide bundle | Pass the same artifact resource scope used by application registration. |
| Artifact comparison does not record both source records | A comparison result loses its evidence trail or cannot support a follow-up unknown | Resolve and record both evidence sources before recording the derived comparison. |
| Rizin command cleanup fails after a mutating call | The active analysis snapshot or target state can no longer be trusted | Retain the partial observation and report retirement failure through the external-mutation path. |
| A provider operation omits its managed path and no server selection exists | The call cannot identify the managed file to inspect | Require an explicit path or select a managed artifact before the dependent operation. |
| Artifact extraction uses a caller-controlled execution root | Extraction can write outside the server's controlled output area | Replace the requested root with a server-created extraction destination. |
Key files
| File | Why to read it |
|---|---|
| src/…/createServer.ts | Shows how the server assembles capability modules, services, session state, and provider policy. |
| src/…/toolContracts.ts | Shows the ordered public contract inventory and capability families. |
| src/…/toolContractTypes.ts | Defines the public contract fields shared by every tool. |
| src/…/toolEffects.ts | Defines the effect audit, MCP safety annotations, and target-content default. |
| src/…/toolRegistrationOptions.ts | Shows how a product contract becomes MCP registration metadata. |
| src/…/contractToolBindings.ts | Shows how named contracts select shared handlers and become MCP tools. |
| src/…/providerOperationToolHandler.ts | Shows the common path for provider-backed evidence operations. |
| src/…/providerOperationFamilies.ts | Shows provider-specific routing and controlled artifact extraction parameters. |
| src/…/registerOfficialTools.ts | Shows how named analysis operations become direct MCP tools. |
| src/…/registerApplicationTools.ts | Shows the provider-neutral application workflow group and its registration order. |
| src/…/types.ts | Shows the shared services that application workflow registration can use. |
| src/…/helpers.ts | Shows source recording, complete-result retention, selected views, and scoped unknowns. |
| src/…/registerGuidanceTools.ts | Shows provider-free guide search and section retrieval. |
| src/…/registerGuidedWorkflowTool.ts | Shows provider-free guided workflow access and family scoping. |
| src/…/registerPrompts.ts | Shows how guided prompts and argument completion follow advertised capabilities. |
| src/…/registerArtifactTools.ts | Shows summary delivery and controlled extraction for artifact inspections. |
| src/…/registerBrowserTools.ts | Shows grouped browser operations, optional-provider diagnostics, retained views, and evidence delivery. |
| src/…/registerElectronTools.ts | Shows Electron inspection, application analysis, runtime reconciliation, active scenarios, and fuse inspection. |
| src/…/registerEnhancedTools.ts | Shows how higher-level workflows use the same contract and evidence model. |
| src/…/registerSessionTools.ts | Shows the session-only lifecycle, context, comparison, process, and cleanup tool groups. |
| src/…/registerSessionRecordTools.ts | Shows evidence bundle and residual-unknown operations. |
| src/…/registerArtifactComparisonTool.ts | Shows evidence-backed artifact comparison and incomplete-result unknowns. |
| src/…/registerInvestigationTools.ts | Shows evidence-backed derived investigation operations. |
| src/…/registerWasmTools.ts | Shows WASM inspection and interface comparison through shared evidence handlers. |
| src/…/registerReverseEngineeringTools.ts | Shows objdump and Rizin registration with target-mutation handling. |
| src/…/registerFridaTools.ts | Shows device discovery, persistent instrumentation, partial evidence, and session cleanup. |
| src/…/registerGdbTools.ts | Shows debugger sessions, retained summaries, mutation admission, and cleanup. |
| src/…/EvidenceMcpServer.ts | Shows how registrations keep canonical contracts while adapting the client-facing wire view. |
Related pages: MCP server, Session evidence and results, Server lifecycle and policy