@gleanwork/mcp-config-schema weekly downloads statistics

@gleanwork/mcp-config-schema

Type-safe configuration schemas and builders for MCP (Model Context Protocol) clients.

The Problem

MCP servers need to work across many different AI coding assistants—Claude Code, VS Code, Cursor, Claude Desktop, Windsurf, Goose, Codex, and more. Each client has its own:

• Configuration format: JSON, YAML, or TOML • File location: Different paths on macOS, Linux, and Windows • Property names: url vs serverUrl vs uri, command vs cmd, mcpServers vs servers vs extensions • Transport support: Some support HTTP natively, others require the mcp-remote bridge • Authentication patterns: Headers, environment variables, or OAuth

Without a unified solution, MCP server authors face a maintenance nightmare: writing and maintaining separate configuration logic for each client, tracking which clients support which features, and keeping up with changes across the ecosystem.

The Solution

This package provides a single source of truth for MCP client configurations. You describe your connection once, and it generates the correct configuration for any supported client:

The package handles all the complexity: format differences, property mapping, platform-specific paths, transport bridging, and one-click installation URLs.

Installation

Quick Start

stdio Transport (Local Server)

For stdio transport, provide registry options with your package names, then pass environment variables directly:

HTTP Transport (Remote Server)

For connecting to HTTP-based MCP servers, no additional configuration is needed:

HTTP Transport with Headers

For HTTP transport with authentication or custom headers:

URL Templates with Variables

For dynamic URLs with template variables (aligned with MCP registry specification):

What This Package Does

This package serves as the Single Source of Truth for MCP client configurations. It provides:

• Registry of all MCP clients and their capabilities • Configuration builders that generate correct configs for each client • Type-safe schemas with TypeScript types and Zod validation • Browser support for web-based configuration tools • Client detection to identify which clients need special handling

Supported Clients

For detailed configuration examples and requirements for each client, see CLIENTS.md.

Centrally Managed Clients

• ChatGPT - Requires web UI configuration • Claude for Teams/Enterprise - Managed by organization admins

Core Usage

Query Client Capabilities

Client Types

Every client declares one or more types describing where it runs. A client can be more than one (e.g. Goose ships both a desktop app and a CLI). Use these to group or filter clients by surface — for example, to build a filterable list of supported hosts:

Installability is a separate axis (userConfigurable): user-installable clients vs. centrally managed ones.

Consumers can provide setup destinations for centrally managed clients without adding vendor-specific URLs to the shared client metadata:

Generate Configurations

Partial Configuration (without root object)

The includeRootObject option allows you to generate just the server configuration entry without the outer wrapper (mcpServers, servers, or extensions depending on the client). This is useful when you need to merge configurations into an existing setup:

Validate Configurations

Browser Support

This package works in browsers! Use the /browser import path:

Note: File operations (writeConfiguration, getConfigPath) are not available in browsers and will throw clear error messages.

React Example

Configuration Examples

📖 For complete configuration examples for all clients, see CLIENTS.md

Native HTTP Client (Claude Code, VS Code)

stdio-only Clients (Claude Desktop, Junie, JetBrains AI)

These clients require mcp-remote bridge for HTTP servers:

Goose (YAML format with native HTTP)

API Reference

For complete API documentation, see the TypeScript definitions in src/types.ts and src/registry.ts. All exports include JSDoc comments.

Key exports:

• MCPConfigRegistry - Main entry point for creating configuration builders • BaseConfigBuilder - Base class for client-specific builders • MCPConnectionOptions - Options for buildConfiguration() • RegistryOptions - Options for customizing the registry • ClientId - Union type of all supported client identifiers

Development

Documentation

• CLIENTS.md - Comprehensive client compatibility matrix with detailed configuration examples • API Reference - Complete API documentation

Icons

Each client ships an SVG host icon, available as an inline string (no bundler/loader setup) and as a raw file under icons/:

Icons are optional per client; getClientIcon returns undefined when one isn't shipped. Internal SVG ids are namespaced per icon, so multiple icons can be inlined on the same page without collisions. See icons/README.md to add or update one.

Trademarks

Product names and the client icons under icons/ are trademarks of their respective owners. They are included only to identify the MCP host applications this package supports (nominative use); their inclusion does not imply affiliation with or endorsement by those owners. Brand icons are sourced from svgl, Simple Icons (CC0), and official brand assets.

License

MIT - See LICENSE file for details

Contributing

This package is part of the Glean MCP ecosystem. For issues and contributions, please visit the repository.

Description from the npm listing.