MCP Framework: A TypeScript Scaffold for Model Context Protocol Servers

The problem mcp-framework solves for TypeScript MCP server authors

Writing a Model Context Protocol server against the official SDK means wiring up the server object, registering handlers, deciding on a transport, and keeping your JSON schemas in sync with your TypeScript types. The README positions MCP Framework as the layer above that: it states that the framework "gives you architecture out of the box, with automatic directory-based discovery for tools, resources, and prompts." The intended user is a TypeScript developer who wants to add a tool by creating a file rather than by editing a central registration list.

The package is published as mcp-framework, with three binaries: mcp, mcp-framework, and mcp-build. It requires Node 18.19.0 or newer, and it declares @modelcontextprotocol/sdk ^1.29.0 and zod 3.x as peer dependencies, so your project supplies those itself. That peer-dependency choice is worth noting: it means the SDK version is your decision, and a breaking SDK change is something you absorb rather than something the framework hides from you.

Directory discovery, base classes and the build-time validation gate

The mechanism is convention over registration. You define a class that extends MCPTool, give it a name, a description, and a schema, and export it as the default export of a file. The framework finds it. The README's example uses this shape, importing MCPTool and MCPInput from mcp-framework and z from zod.

The part that separates this framework from a thin SDK wrapper is validation. The mcp validate command checks that every field in a Zod object schema carries a .describe() call, and the README shows the failure text: a tool named price_fetcher missing descriptions for symbol and currency fails the build with a message pointing at the file and the fields. Validation runs in three places according to the README: during npm run build, standalone via mcp validate, and at server startup before accepting connections. The build can be forced or skipped with the MCP_SKIP_TOOL_VALIDATION environment variable, which the README marks as not recommended when set to true.

That gate is a real design opinion. It treats an undescribed schema field as a defect, on the grounds that the model reading the tool definition needs the description to call the tool correctly. If you have a large existing tool set with bare z.string() fields, the first build after adopting the framework will fail until you annotate them. That is the intended behaviour, not a bug, but it is work.

Installing mcp-framework and creating a first server

The README recommends the CLI. Install the framework globally, then generate a project. The generator writes a working server so you can run it before you write any tool code.

npm install -g mcp-framework
mcp create my-mcp-server
cd my-mcp-server

After this, the README states your server is ready to use. The generated project compiles with npm run build, which runs tsc and, per the README, validates your tool schemas as part of the same command. To add a tool without writing the file by hand, use the add subcommand:

mcp add tool price-fetcher
npm run build

If you want the HTTP transport instead of the default stdio, the generator takes flags. The README warns that --cors sets the allowed origin to "*" and that you should modify it in the index file if you do not want that.

mcp create my-mcp-server --http --port 1337 --cors

To connect the built server to Claude Desktop, the README gives a config block pointing at the compiled entry point. On macOS the file is ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows it is %APPDATA%/Claude/claude_desktop_config.json.

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp-server/dist/index.js"]
    }
  }
}

The reader should expect the server to appear in the client's MCP server list after a restart, with the tools they defined listed under it. If nothing appears, the first thing to check is that the path in args is absolute and points at dist/index.js rather than the TypeScript source.

Where mcp-framework is the wrong tool

The HTTP transport is labelled EXPERIMENTAL in the README. That word appears next to the mcp create --http example, and it is the strongest signal in the document about production readiness. If you need a network-reachable MCP server with authentication, the framework does ship OAuth 2.1, JWT and API key support for SSE endpoints, but the README itself does not explain how to configure any of it. The repository root carries OAUTH_GUIDE.md, OAUTH_QUICK_START.md, OAUTH_IMPLEMENTATION_PLAN.md, OAUTH_USER_STORY.md, SECURITY_AUDIT.md and MERGE_OAUTH_WITH_HTTPSTREAM.md, which tells you the authentication work is documented in scattered files rather than in the main README. That is a maintenance surface you inherit.

The second limitation is the language boundary. This is a TypeScript framework with a TypeScript build step and a TypeScript CLI. The related searches around Python, Go and MATLAB production server point at demand the project does not serve. If your team is not on Node, nothing here transfers, and the peer dependency on zod 3.x means a project already on a future zod major would need to reconcile versions before the framework will install cleanly.

Third, the validation gate is opinionated enough to be a blocker in some workflows. A repository with many tools and no field descriptions cannot build until every Zod object field is annotated. MCP_SKIP_TOOL_VALIDATION=true exists as an escape hatch, but the README calls skipping validation not recommended, so treating it as a permanent setting is working against the tool.

mcp-framework compared with FastMCP and with calling the SDK directly

The related searches include "mcp framework vs fastmcp", and the honest answer from the published documentation is that the two sit in different language ecosystems. FastMCP is the Python-side equivalent: a framework that turns decorated functions into MCP tools. MCP Framework is the TypeScript-side equivalent, built on the official MCP SDK and using classes with Zod schemas instead of decorators. The difference that matters in practice is the type system. Here your tool input type is derived from the Zod schema through MCPInput<this>, so a change to the schema propagates into the execute signature. In a Python framework the same guarantee comes from type hints at best.

The second comparison is against the official SDK on its own. The SDK gives you the protocol; it does not give you directory discovery, a generator, or the schema validation gate. If you have one or two tools and you like explicit registration, the SDK alone is fewer moving parts and one fewer peer dependency to track. MCP Framework earns its place when the tool count grows and the registration list becomes the thing people forget to update.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-04-16, which is the same date as the mcp-framework-v0.2.22 release. The two prior releases, v0.2.21 and v0.2.20, both landed on 2026-04-02. So the release cadence visible here is patch-level and clustered, not a steady weekly train, and the version number is still 0.x. Treat the API as pre-1.0: minor-version bumps are where breaking changes are allowed to live.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the whole of what the repository states, and it is not legal advice; if you are redistributing the framework inside a product, have your own counsel read the LICENSE file.

The upgrade cost is concentrated in two places. First, the peer dependencies: @modelcontextprotocol/sdk ^1.29.0 and zod 3.x are yours to keep current, and a major bump in either is an upgrade you plan for. Second, the validation gate means a framework upgrade that tightens validation rules can break your build, not your runtime, which is the better failure mode but still a build you have to fix. The repository also carries a CHANGELOG.md at the root, which is where you should look before bumping rather than reconstructing changes from release tags.

Editorial conclusion

Adopt mcp-framework if your team writes TypeScript, wants a project scaffold rather than a hand-rolled SDK wrapper, and can live with Node 18.19 or newer plus peer dependencies on @modelcontextprotocol/sdk ^1.29.0 and zod 3.x. Do not adopt it if your stack is Python or Go, or if you need the HTTP transport in production and are unwilling to audit the OAuth code paths yourself. Before committing, run mcp create in a throwaway directory, run npm run build to see the validation pass, and read OAUTH_GUIDE.md and SECURITY_AUDIT.md in the repository, because the README does not document the authentication surface in detail.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. QuantGeekDev/mcp-framework on GitHub
4. README
5. Releases