MCP Layer

Build production-ready interfaces on top of any MCP server without rewriting transport, schema, or adapter plumbing.

MCP Layer is a collection of focused packages that help you discover server configs, connect sessions, normalize catalogs, and expose those capabilities through CLI, REST, and GraphQL surfaces. You can adopt one package at a time, or use the aggregate mcp-layer package when you want a single import path.

Why teams use MCP Layer

• Ship faster: start from a real MCP server and generate usable interfaces quickly.
• Keep contracts consistent: drive adapters from one normalized catalog.
• Stay portable: align with MCP transport semantics and official SDK behavior.
• Scale safely: shared validation, resilience, and telemetry primitives are built in.

What you can build

• CLI tooling for MCP tools, prompts, resources, and templates.
• REST gateways with OpenAPI 3.1 output.
• GraphQL gateways backed by MCP catalogs.
• Internal developer portals and UI layers over MCP resources.
• Integration test harnesses using a feature-complete local MCP server.

Package catalog

Foundation and runtime

Interfaces and adapters

Aggregate package

Quick start

This first example is the fastest path to validate an end-to-end MCP workflow in your own environment. It discovers config, opens a session, extracts the normalized catalog, and prints item names.

import { load } from '@mcp-layer/config';
import { connect } from '@mcp-layer/connect';
import { extract } from '@mcp-layer/schema';

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

const catalog = await extract(session);
console.log(catalog.items?.map(function names(item) { return item.name; }) ?? []);

await session.close();

When this succeeds, you should see an array of discovered catalog item names in stdout.

If you prefer a single import during prototyping, the aggregate package exposes the same surface as namespace exports:

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();

That run should print the catalog item count while keeping version alignment across package namespaces.

Use this pattern when you want deterministic API contracts in tests or local tooling, without depending on an external MCP deployment.

import { attach } from '@mcp-layer/attach';
import { extract } from '@mcp-layer/schema';
import { spec } from '@mcp-layer/openapi';
import { build } from '@mcp-layer/test-server';

const server = build();
const session = await attach(server, 'local');

const catalog = await extract(session);
const openapi = spec(catalog, {
  title: 'Local MCP API',
  version: '0.1.0',
  prefix: '/v1'
});

console.log(openapi.openapi);

await session.close();
await server.close();

A healthy run prints 3.1.0 and gives you a complete OpenAPI document from the live catalog.

CLI quick try

If you already have an MCP config on disk, this is the quickest way to confirm discovery and command generation are working:

mcp-layer servers list
mcp-layer tools list --server <name>
mcp-layer tools <tool> --help

You should first see discovered server names, then tool inventory and command-level help for the chosen server.

API reference (mcp-layer aggregate package)

The aggregate package does not add a custom runtime abstraction. It re-exports package namespaces so you can import once and compose as needed.

Module shape

import {
  attach,
  cli,
  config,
  connect,
  error,
  gateway,
  graphql,
  manager,
  openapi,
  rest,
  schema,
  session,
  testServer
} from 'mcp-layer';

Each namespace value is the module namespace of its underlying package (typeof import('<package>')).

Namespace exports

Error behavior

Errors come from the underlying package implementations. The aggregate package does not wrap or remap those contracts.

For package-specific runtime error references and remediation steps:

• @mcp-layer/config runtime error reference
• @mcp-layer/rest runtime error reference
• mcp-layer package error behavior

Standards and portability

MCP Layer is standards-first, with host-specific behavior isolated to connectors and runtime options.

• MCP specification: Model Context Protocol
• MCP transports: Transport specification
• SDK baseline: @modelcontextprotocol/sdk

For host-tool config schema references (Claude, Cursor, Codex, VS Code, Cline, and others), use the connector documentation in @mcp-layer/config.

Development workflow

pnpm install
pnpm build:types
pnpm test

These commands install workspace dependencies, generate declaration files from the package JSDoc into each package-local types/ directory, and run all package test suites from the repository root. Root test discovery intentionally targets packages/*/test/**/*.test.js so fixture programs in test/fixtures/ are never executed as standalone tests. The repository CI workflow also enforces job/step timeouts and cancels superseded runs per branch to avoid stuck jobs consuming runner minutes. Generated declaration output is intentionally ignored from Git and rebuilt during pnpm test and package publish flows.

When iterating on a single area, run package-scoped commands:

pnpm --filter @mcp-layer/config test
pnpm --filter mcp-layer prepack
pnpm --filter mcp-layer test

Release workflow

MCP Layer uses Changesets and a GitHub Actions release workflow.

1. Create a changeset with pnpm changeset.
2. Merge the generated version PR (changeset-release/main).
3. Publish through the Release GitHub Actions workflow (npm Trusted Publishing / OIDC), which runs on node-version: lts/*.

Trusted publishing requirements are defined by npm:

• Trusted publishing with OIDC
• Generating provenance statements

The aggregate package prepack behavior is maintained in packages/mcp-layer.

Repository guidelines

Contributor standards and required workflows are documented in AGENTS.md.

License

MIT