MCP Framework scaffolds TypeScript servers, and its --cors flag ships a wildcard origin
The Typescript MCP Framework
At a glance
- What is it?
- mcp-framework is a TypeScript framework for Model Context Protocol servers with directory based discovery, three transports, and out of the box authentication. Two things in it deserve a second look before you scaffold anything: a global install that puts a command named mcp on your PATH, and a scaffold flag that sets a wildcard CORS origin.
- Who is it for?
- This fits someone who wants their MCP server to look like a directory of typed classes rather than a registration module, and who will read the generated index file once. Four things to check first.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Activity is slowing. The repository last received commits 7 months ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- QuantGeekDev/mcp-framework930 ★ · +0
| Repository | 2026-09-10 | 2026-11-15 |
|---|---|---|
| QuantGeekDev/mcp-framework | 930 | 930 |
0 Stars in the last 66 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
A global install puts three commands on your PATH, one called mcp
The recommended setup is one global install followed by a scaffold:
# Install the framework globally
npm install -g mcp-framework
# Create a new MCP server project
mcp create my-mcp-serverThe package registers three binaries, not one. `mcp` and `mcp-framework` both point at the same CLI entry point, and a third, `mcp-build`, points at the build CLI. So installing this globally puts a command called `mcp` on the path of anyone who runs that command, which is a short enough name that it is worth checking what already answers to it.
The package is ESM only, with the type set to module, a single export entry carrying the types and the import, and a files array containing only the built output. Subpaths are not exported, so the CLI internals are reachable as binaries and not as imports.
The engine floor is Node 18.19.0. The prepare script runs the build, which means installing from a git checkout compiles TypeScript as part of the install rather than asking you to do it.
The scaffold's CORS flag sets a wildcard origin and leaves the fix to you
The project creation command takes three options, and one of them carries its own warning in the page:
# Create a new project with the new EXPERIMENTAL HTTP transport
# Heads up: This will set cors allowed origin to "*", modify it in the index if you wish
mcp create <your project name here> --http --port 1337 --cors`--http` switches away from the default stdio transport, `--port` sets the HTTP port and defaults to 8080, and `--cors` enables CORS with wildcard access, which the tool implements by writing an allowed origin of `*` into the generated file.
Two details sit next to each other in the source. The warning is there, which is more than most scaffolds do, and it is phrased as a manual follow-up rather than as a prompt. And the same page's feature list advertises multiple transport support across stdio, SSE, and HTTP Stream, without the experimental label that the CLI carries. So the transport you are told is fully supported in one place is the one the command line calls new and experimental in another.
The practical order of operations matters: scaffold, then open the index file, then narrow the origin, because nothing between those two steps will stop you from starting the server.
The build script is tsc, so the automatic validation comes from a binary you add
Validation is the part of this framework with the most attention paid to it, and the mechanism has a wrinkle. Tools that use Zod object schemas must have a description on every field, and the check can be run four ways: during the build, standalone through the `mcp validate` command, inline while you develop through a `defineSchema()` helper, and again when the server starts. The build and the runtime check are the ones that catch a missing description before a client sees it.
The build is toggled by an environment variable whose polarity is worth reading twice:
MCP_SKIP_TOOL_VALIDATION=false npm run build # Force validation (default)
MCP_SKIP_TOOL_VALIDATION=true npm run build # Skip validation (not recommended)So the variable is named for skipping, and the value that means do the work is the false one. The page also shows how to put the check in a project's own scripts, and there the build line is `tsc && mcp-build`, with validation also in the test and prepack scripts.
That is the wrinkle: the framework's own build script is a plain `tsc`, and `mcp-build` is a separate binary. So the automatic validation described in the prose happens in a project whose build script has been rewritten to include that binary, and a project that leaves its build as generated gets a compile step and no check.
One more detail, in the sample error: it names a `.js` file, in a framework that is TypeScript first.
The worked example is a file called DataFetcher containing a tool called add
The development workflow walks through seven steps and shows a complete tool. The file is introduced as `tools/DataFetcher.ts`, the step above it adds three tools named data-fetcher, data-processor, and report-generator, and the code inside declares a class called `AddTool` with the name `add` and a two-number schema described as a first and a second number to add.
// tools/DataFetcher.ts
import { MCPTool, MCPInput as AddToolInput } from "mcp-framework";
import { z } from "zod";
const AddToolSchema = z.object({
a: z.number().describe("First number to add"),
b: z.number().describe("Second number to add"),
});
class AddTool extends MCPTool {
name = "add";
description = "Add tool description";
schema = AddToolSchema;
async execute(input: AddToolInput<this>) {
const result = input.a + input.b;
return `Result: ${result}`;
}
}
export default AddTool;So the example is the add tool, in a file named after a fetcher, sitting under a heading that describes data fetching. What it does show clearly is the shape: a base class, a name, a description, a Zod schema where every field carries a description, and an async execute whose input is typed with a self reference so the editor can complete the schema's fields.
The server is then started with `node dist/index.js`, at which point it validates the tools again before accepting connections.
Five OAuth documents and two merge scripts sit at the repository root
The top level tells a story about where the project is. Five files are named after OAuth work: a guide, an implementation plan, an implementation summary, a quick start, and a user story, plus a sixth document about merging OAuth with the HTTP stream. Two shell scripts at the root are named `merge-oauth.sh` and `complete-merge.sh`.
Alongside them sit a security audit and a performance report as root documents, and both a `CHANGELOG.md` and a `CHANGES.md`. Then the ordinary tooling: an ESLint flat config, a Prettier config, a Jest config, a TypeScript config, a cursor rules directory, an agent instructions file, and a Claude instructions file.
The layout is mixed as well. Both `src/` and `packages/` are present, which is either a monorepo in progress or a directory that was introduced and not removed. Two environment templates are committed, one for an AI provider and one for Cognito, and the examples directory is dominated by OAuth: a Cognito example for Claude, a simplified Cognito example, a custom validator example, a simple OAuth example, a test client, and an `oauth-server` directory.
Releases are managed by release-please, with its config and manifest at the root, which is where the tag format comes from: the newest three are `mcp-framework-v0.2.22`, `v0.2.21`, and `v0.2.20`, and the last two landed on the same day an hour apart.
zod is a peer dependency and a dependency, and TypeScript ships at runtime
The dependency list is short and says what the framework actually needs. The official MCP SDK is a peer dependency at 1.29.0 or newer, and zod is a peer dependency pinned to the 3.x line, which is also how it appears in the regular dependencies. Declaring the same package on both sides is not an error, and it is how a framework gets the version it was tested against while leaving the host project in control, but it does mean an install can end up with two copies if the host is on a different line.
TypeScript is a regular dependency rather than a development one, which is unusual and explicable: the build CLI is compiled into the published output and has to type check a consumer's project, so the compiler travels with the package.
The rest divides cleanly. The authentication path is `jsonwebtoken`, `jwks-rsa`, and, for reading request bodies, `raw-body` and `content-type`. The command line is `commander`, `prompts` for interactive scaffolding, `find-up` for locating a project, and `execa` for running subprocesses. Configuration is `dotenv`.
That is the honest shape of a framework whose selling point includes out of the box authentication: the JWT machinery is in the dependencies, and the OAuth 2.1 story is a transport option rather than a dependency of its own.
Three environment variables, all defaulting to off
The configuration surface named on the page is three variables and a table. `MCP_ENABLE_FILE_LOGGING` turns file logging on and defaults to false. `MCP_LOG_DIRECTORY` says where those files go and defaults to `logs`. `MCP_DEBUG_CONSOLE` turns debug level console output on and defaults to false.
All three default to quiet, which is the right default for something that might be launched by another process. Nothing on that table sets the transport, the port, the authentication provider, or the discovery paths, so those either come from the scaffold's generated file or from flags the page does not enumerate.
That gap is worth naming against the feature list, which claims out of the box authentication for SSE endpoints with OAuth 2.1, JWT, and API keys. The variables that would select a mode are not in the table, and the OAuth design documents in the repository root are the only place the page points to for detail.
The one named project is also the donation link
There is a section for projects built with the framework, and it contains one entry. That entry is tip.md, described as a crypto tipping service that lets an assistant help a user send cryptocurrency tips to a content creator from the chat interface, with the MCP service checking wallet types and preparing a tip for the user or agent to complete. Setup instructions for Cursor, Sage, and Claude Desktop are pointed at elsewhere.
The same project appears again immediately below, under a heading that asks for support, as a link to that account. So the reference project and the funding request are the same destination, which is worth knowing when you weigh how representative the single example is.
The release record is short and recent in a way the rest of the page does not advertise: v0.2.22 on 2026-04-16, v0.2.21 and v0.2.20 both on 2026-04-02, and the last commit to the main branch on 2026-04-16. Three patch releases inside a fortnight, with the project still on a 0.2 line.
Editorial conclusion
This fits someone who wants their MCP server to look like a directory of typed classes rather than a registration module, and who will read the generated index file once. Four things to check first. What a global install puts on your PATH, since one of the three command names is short enough that something else on your machine may already answer to it. What the scaffold's CORS flag leaves you with, because the tool sets a wildcard origin and the instruction to narrow it is a note rather than a default. Whether the validation you have read about actually runs in your build, since the framework's own build script is a plain tsc and the validation hook is a separate binary you have to wire in. And which authentication mode you are relying on, since the page advertises OAuth 2.1, JWT, and API keys as built in while the root of the repository still holds five OAuth design documents and two merge scripts.
Frequently asked questions
How do I create a new server with the mcp-framework CLI?
Install the package globally with npm install -g mcp-framework, then run mcp create my-mcp-server and change into the directory. The scaffold sets up tools, resources, and prompts discovered from the directory layout, and the server is then started with node dist/index.js.
What does the --cors flag do in mcp create?
It enables CORS with wildcard access, setting the allowed origin to *. The page calls the HTTP transport experimental and tells you to change the origin in the index if you want something narrower. The port flag defaults to 8080, and the default transport is stdio.
Does npm run build validate tools in mcp-framework?
The framework's own build script is a plain tsc. Validation runs through a separate mcp-build binary that the page shows wired into a project as tsc && mcp-build, it can be skipped with MCP_SKIP_TOOL_VALIDATION=true, and it can be run on its own with mcp validate or again when the server starts.
Which commands does npm install -g mcp-framework put on my PATH?
Three: mcp, mcp-framework, and mcp-build, with the first two pointing at the same CLI entry point and the third at the build CLI. The package publishes only its built output, and its exports map has a single root entry, so subpaths are not importable.
What does mcp-framework need at runtime?
Node 18.19.0 or newer, with the official MCP SDK as a peer dependency at 1.29.0 or newer and zod on the 3.x line, which is declared both as a peer and as a regular dependency. TypeScript also ships as a runtime dependency because the build CLI is part of the published output.
What has been built with the MCP Framework?
The page names one project, tip.md, a crypto tipping service where an assistant checks wallet types and prepares a tip for the user to complete, with setup instructions for Cursor, Sage, and Claude Desktop. It appears again under a heading that carries the sponsorship link to the same account.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/quantgeekdev-mcp-framework)Star history chart for your README
[](https://hysenlabs.com/projects/quantgeekdev-mcp-framework)Was this useful?