mcp-layer

mcp-layer

mcp-layer is the npm entry point for MCP Layer, a toolkit for building production-ready interfaces on top of any MCP server.

Use it to discover MCP configs, connect sessions, normalize catalogs, and expose those capabilities through CLI, REST, GraphQL, and OpenAPI layers in one cohesive stack.

Install

Use your package manager of choice to install mcp-layer in any Node.js project.

npm install mcp-layer
pnpm add mcp-layer
yarn add mcp-layer

Quick Start

This example demonstrates the primary workflow: load MCP configuration, open a session, and extract a normalized catalog from one package import. This matters when you want to wire a prototype quickly without managing multiple top-level dependencies.

import { config, connect, schema } from 'mcp-layer';

const cfg = await config.load(undefined, process.cwd());
const session = await connect.connect(cfg, 'demo');
const catalog = await schema.extract(session);

console.log(catalog.items?.length ?? 0);
await session.close();

Running this script prints the number of discovered catalog items for the selected server.

API Reference

mcp-layer exports package namespaces. If you are new to MCP Layer, this table explains what each namespace is for and links to full package documentation.

Namespace export	Purpose	Documentation
attach	Attach to in-process MCP SDK servers without launching external transports.	@mcp-layer/attach README
cli	Build command-line interfaces for MCP tools, prompts, resources, and templates.	@mcp-layer/cli README
config	Discover and normalize MCP server configuration across host tools.	@mcp-layer/config README
connect	Connect to MCP servers over stdio, Streamable HTTP, or SSE.	@mcp-layer/connect README
error	Create structured runtime errors with stable references and docs links.	@mcp-layer/error README
gateway	Reuse shared adapter runtime primitives for mapping, validation, resilience, and telemetry.	@mcp-layer/gateway README
graphql	Expose MCP catalogs and operations through GraphQL.	@mcp-layer/graphql README
manager	Manage authenticated and shared MCP sessions with reuse and limits.	@mcp-layer/manager README
openapi	Generate OpenAPI 3.1 documents from MCP catalogs.	@mcp-layer/openapi README
rest	Expose MCP sessions as REST endpoints with Fastify.	@mcp-layer/rest README
schema	Extract and normalize tools, resources, prompts, and templates into a consistent catalog.	@mcp-layer/schema README
session	Use the shared session abstraction across connectors and adapters.	@mcp-layer/session README
testServer	Run a feature-complete local MCP server for development and integration tests.	@mcp-layer/test-server README

Error Behavior

This package does not introduce a custom runtime layer. Errors are raised by whichever namespace package you call.

For structured runtime errors, refer to the package-level error sections in the linked namespace READMEs.

findWorkspaceRoot: Unable to locate workspace root from mcp-layer package.

This error is raised when mcp-layer package generation runs in a directory tree that does not contain pnpm-workspace.yaml.

Step-by-step resolution:

• Run generation from inside a checkout of the MCP Layer repository.
• Confirm pnpm-workspace.yaml exists at the repository root.
• Run pnpm --filter mcp-layer prepack from the repository root.

Debug example

If you copy packages/mcp-layer into a standalone folder and run node src/generate.js, findWorkspaceRoot cannot locate the workspace marker and throws this error.

Standards and Portability

MCP behavior follows the official MCP specification and official TypeScript SDK contracts:

• Model Context Protocol specification
• MCP transport specification
• Model Context Protocol TypeScript SDK

License

MIT