mcp-z-client

@mcp-z/client

@mcp-z/client manages MCP server configuration, process startup, connections, discovery, calls, and cleanup. Use the package's wrappers for ordinary tool, prompt, and resource calls. Reach for the raw MCP SDK responses only when the wrapper omits data the caller needs.

Install

npm install @mcp-z/client

Read the consuming project's existing MCP configuration before inventing one. A standard .mcp.json stores entries under mcpServers.

Use the client

HTTP entries include type: 'http'. Stdio entries use command and optional args and env.

registry.close() closes every managed client and spawned process. Keep it in finally, or use await using registry = createServerRegistry(config) when the consuming runtime and project conventions support explicit resource management.

Tool names and schemas belong to the connected server, not this skill. Call client.listTools() before composing an unfamiliar invocation and use the returned input schema. Discovery is read-only. A tool call may change external state, so the call must stay within the user's requested action.

The convenience methods accept simple arguments:

• client.callTool(name, args)
• client.getPrompt(name, args)
• client.readResource(uri)

Their response wrappers expose json(), text(), and raw(). For tools, json() returns structuredContent when present and otherwise parses the first text block. Wrapper methods throw a typed response error for MCP error results or incompatible content.

Use callToolRaw(), getPromptRaw(), or readResourceRaw() only when the caller needs the untouched SDK response.

Examples

• Connect to a public server
• Spawn a local server
• Use multiple servers
• Discover capabilities
• Embed a server cluster
• Test an MCP server

Connection options

createServerRegistry(config, { cwd, env, dialects }) controls spawned processes. Supplying env replaces the base environment rather than merging with process.env.

The default dialects: ['servers'] starts stdio command entries. An HTTP entry with a start block needs dialects: ['start'], or ['servers', 'start'] when both forms should start.

registry.connect(name, { versionNegotiation: { mode: 'auto' } }) probes for the current protocol revision and falls back to the legacy sequence. Pin a revision only when the caller requires that exact protocol.