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:

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

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