McpService
katanakit-js / McpService
Class: McpService
Section titled “Class: 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.
Example
Section titled “Example”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]));Methods
Section titled “Methods”useAddMcpServer()
Section titled “useAddMcpServer()”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.
Parameters
Section titled “Parameters”| 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 |
- |
Returns
Section titled “Returns”{ 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
Section titled “createdAt”createdAt: string;keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string;}[];Type Declaration
Section titled “Type Declaration”mcpServers
Section titled “mcpServers”mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string;}[];Type Declaration
Section titled “Type Declaration”updatedAt
Section titled “updatedAt”updatedAt: string;version
Section titled “version”version: 1;useCreateMcpServer()
Section titled “useCreateMcpServer()”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.
Parameters
Section titled “Parameters”| 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 |
- |
Returns
Section titled “Returns”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()
Section titled “useEmitOpenCodeServers()”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).
Parameters
Section titled “Parameters”| 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. |
Returns
Section titled “Returns”SafeResult<string>
{ data, error, ok } with the JSON text.
useFindMcpServer()
Section titled “useFindMcpServer()”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.
Parameters
Section titled “Parameters”| 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. |
Returns
Section titled “Returns”| {
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()
Section titled “useListMcpServers()”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.
Parameters
Section titled “Parameters”| 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 |
- |
Returns
Section titled “Returns”{
command?: string[];
disabled?: boolean;
environment?: Record<string, string>;
headers?: Record<string, string>;
name: string;
type: "local" | "remote";
url?: string;
}[]
The server entries.
useOpenCodeServersObject()
Section titled “useOpenCodeServersObject()”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.
Parameters
Section titled “Parameters”| 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. |
Returns
Section titled “Returns”SafeResult<Record<string, OpenCodeMcpServer>>
{ data, error, ok } with the name-keyed object.
useRemoveMcpServer()
Section titled “useRemoveMcpServer()”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.
Parameters
Section titled “Parameters”| 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. |
Returns
Section titled “Returns”{ 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
Section titled “createdAt”createdAt: string;keys: { createdAt: string; id: string; label: string; note?: string; provider: string; secret: string; status: "active" | "revoked"; updatedAt: string;}[];Type Declaration
Section titled “Type Declaration”mcpServers
Section titled “mcpServers”mcpServers: { command?: string[]; disabled?: boolean; environment?: Record<string, string>; headers?: Record<string, string>; name: string; type: "local" | "remote"; url?: string;}[];Type Declaration
Section titled “Type Declaration”updatedAt
Section titled “updatedAt”updatedAt: string;version
Section titled “version”version: 1;getInstance()
Section titled “getInstance()”static getInstance(): McpService;Defined in: core/services/mcp.service.ts:48
Returns the shared instance (Singleton).
Returns
Section titled “Returns”McpService