Skip to content

McpService

katanakit-js / McpService

Defined in: core/services/mcp.service.ts:41

McpService — Singleton facade for MCP server registry management and host-config emission.

Applies the Singleton pattern (one shared instance via McpService.getInstance) and the Facade pattern: validation failures come back as { data, error, ok }, nothing throws. The methods are pure — registry entries live inside a VaultData payload that the caller owns.

Emission targets the OpenCode mcp.servers contract (local servers run a command over stdio, remote servers are absolute Streamable HTTP URLs). Credential values are kept as {env:NAME} references — the vault holds the secret, generated config holds the indirection.

import { useCreateMcpServer, useEmitOpenCodeServers } from "katanakit-js";
const entry = useCreateMcpServer({ name: "context7", type: "remote", url: "https://mcp.context7.com/mcp" });
if (entry.ok) console.log(useEmitOpenCodeServers([entry.data]));
useAddMcpServer(data, entry): {
createdAt: string;
keys: {
createdAt: string;
id: string;
label: string;
note?: string;
provider: string;
secret: string;
status: "active" | "revoked";
updatedAt: string;
}[];
mcpServers: {
command?: string[];
disabled?: boolean;
environment?: Record<string, string>;
headers?: Record<string, string>;
name: string;
type: "local" | "remote";
url?: string;
}[];
updatedAt: string;
version: 1;
};

Defined in: core/services/mcp.service.ts:88

Adds a server to the registry, replacing any entry with the same name — the same “same name wins wholesale” semantic OpenCode applies to config overrides, so a re-add is an intentional full replacement.

Parameter Type Description
data { createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1; } The current vault payload.
data.createdAt? string -
data.keys? { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[] -
data.mcpServers? { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[] -
data.updatedAt? string -
data.version? 1 -
entry { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; } The server entry to store.
entry.command? string[] -
entry.disabled? boolean -
entry.environment? Record<string, string> -
entry.headers? Record<string, string> -
entry.name? string -
entry.type? "local" | "remote" -
entry.url? string -
{
createdAt: string;
keys: {
createdAt: string;
id: string;
label: string;
note?: string;
provider: string;
secret: string;
status: "active" | "revoked";
updatedAt: string;
}[];
mcpServers: {
command?: string[];
disabled?: boolean;
environment?: Record<string, string>;
headers?: Record<string, string>;
name: string;
type: "local" | "remote";
url?: string;
}[];
updatedAt: string;
version: 1;
}

The updated payload.

createdAt: string;
keys: {
createdAt: string;
id: string;
label: string;
note?: string;
provider: string;
secret: string;
status: "active" | "revoked";
updatedAt: string;
}[];
mcpServers: {
command?: string[];
disabled?: boolean;
environment?: Record<string, string>;
headers?: Record<string, string>;
name: string;
type: "local" | "remote";
url?: string;
}[];
updatedAt: string;
version: 1;

useCreateMcpServer(input): SafeResult<{
command?: string[];
disabled?: boolean;
environment?: Record<string, string>;
headers?: Record<string, string>;
name: string;
type: "local" | "remote";
url?: string;
}>;

Defined in: core/services/mcp.service.ts:61

Creates a validated MCP server entry.

Parameter Type Description
input { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; } Name, type and the transport fields for that type.
input.command? string[] -
input.disabled? boolean -
input.environment? Record<string, string> -
input.headers? Record<string, string> -
input.name? string -
input.type? "local" | "remote" -
input.url? string -

SafeResult<{ command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }>

{ data, error, ok } — error.status = 400 on validation failure.


useEmitOpenCodeServers(servers): SafeResult<string>;

Defined in: core/services/mcp.service.ts:185

Renders registry entries as a pretty-printed mcp.servers JSON fragment, ready to paste into opencode.json(c).

Parameter Type Description
servers { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[] The server entries to render.

SafeResult<string>

{ data, error, ok } with the JSON text.


useFindMcpServer(data, name):
| {
command?: string[];
disabled?: boolean;
environment?: Record<string, string>;
headers?: Record<string, string>;
name: string;
type: "local" | "remote";
url?: string;
}
| undefined;

Defined in: core/services/mcp.service.ts:127

Finds a server by name.

Parameter Type Description
data { createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1; } The vault payload.
data.createdAt? string -
data.keys? { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[] -
data.mcpServers? { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[] -
data.updatedAt? string -
data.version? 1 -
name string The server name.

| { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; } | undefined

The entry, or undefined.


useListMcpServers(data): {
command?: string[];
disabled?: boolean;
environment?: Record<string, string>;
headers?: Record<string, string>;
name: string;
type: "local" | "remote";
url?: string;
}[];

Defined in: core/services/mcp.service.ts:116

Lists registered servers in registration order.

Parameter Type Description
data { createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1; } The vault payload.
data.createdAt? string -
data.keys? { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[] -
data.mcpServers? { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[] -
data.updatedAt? string -
data.version? 1 -

{ command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]

The server entries.


useOpenCodeServersObject(servers): SafeResult<Record<string, OpenCodeMcpServer>>;

Defined in: core/services/mcp.service.ts:142

Projects registry entries into an OpenCode mcp.servers object.

Only the keys the transport uses are emitted: command/environment for local servers, url/headers for remote ones, disabled only when true. Secrets are never interpolated — environment/headers values travel as {env:NAME} references exactly as stored.

Parameter Type Description
servers { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[] The server entries to project.

SafeResult<Record<string, OpenCodeMcpServer>>

{ data, error, ok } with the name-keyed object.


useRemoveMcpServer(data, name): {
createdAt: string;
keys: {
createdAt: string;
id: string;
label: string;
note?: string;
provider: string;
secret: string;
status: "active" | "revoked";
updatedAt: string;
}[];
mcpServers: {
command?: string[];
disabled?: boolean;
environment?: Record<string, string>;
headers?: Record<string, string>;
name: string;
type: "local" | "remote";
url?: string;
}[];
updatedAt: string;
version: 1;
};

Defined in: core/services/mcp.service.ts:102

Removes a server from the registry. Removing an absent name is a no-op.

Parameter Type Description
data { createdAt: string; keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[]; mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[]; updatedAt: string; version: 1; } The current vault payload.
data.createdAt? string -
data.keys? { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string; }[] -
data.mcpServers? { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string; }[] -
data.updatedAt? string -
data.version? 1 -
name string The server name.
{
createdAt: string;
keys: {
createdAt: string;
id: string;
label: string;
note?: string;
provider: string;
secret: string;
status: "active" | "revoked";
updatedAt: string;
}[];
mcpServers: {
command?: string[];
disabled?: boolean;
environment?: Record<string, string>;
headers?: Record<string, string>;
name: string;
type: "local" | "remote";
url?: string;
}[];
updatedAt: string;
version: 1;
}

The updated payload.

createdAt: string;
keys: {
createdAt: string;
id: string;
label: string;
note?: string;
provider: string;
secret: string;
status: "active" | "revoked";
updatedAt: string;
}[];
mcpServers: {
command?: string[];
disabled?: boolean;
environment?: Record<string, string>;
headers?: Record<string, string>;
name: string;
type: "local" | "remote";
url?: string;
}[];
updatedAt: string;
version: 1;

static getInstance(): McpService;

Defined in: core/services/mcp.service.ts:48

Returns the shared instance (Singleton).

McpService