xmcp: file-system routing for TypeScript MCP servers

The problem xmcp targets: MCP servers assembled by hand

The Model Context Protocol defines how a client discovers and calls tools exposed by a server, but it does not say how a TypeScript project should be laid out. Nothing in the protocol tells you where a tool definition lives, how it is registered, or how a request is authenticated before it reaches the handler. In a hand-rolled server each of those decisions is yours, and they tend to be made once and then copied between projects without much thought. xmcp takes a position on them. The README describes it as a framework for building and shipping MCP servers with TypeScript, and the feature list is mostly about conventions rather than protocol machinery. The intended audience is a developer who already knows TypeScript and wants the MCP part to be a directory of files rather than a registration function they maintain by hand. It is not aimed at someone who wants to write an MCP server in Python, Go, or Rust, and nothing in the material suggests a path for that.

How routing and registration work in xmcp

The mechanism named in the README is file-system routing. Tools and prompts are auto-registered from a tools and prompts directory, which means the framework scans those directories and derives the server's exposed surface from what it finds. That is the same idea as a file-based router in a web framework: the path of the file determines the name the client sees, and exporting something from the file determines what the handler does. The README does not show the file contents, so the exact export shape is not something I can state from this material. What can be said is that registration is not a manual step. There is no list of tool definitions to keep in sync with the implementations, because the directory listing is the list. Middleware sits in front of the handlers. The README calls it a toolkit for shipping authentication and custom middlewares, which implies a request passes through middleware before reaching a tool, and that the middleware layer is where you would put a credential check. The order of that chain, and whether middleware can short-circuit a tool call, are not described in the supplied text. Configuration is described as extensible and customizable for your MCP server, again without a key list. That gap matters more than it sounds: with file-system routing, the configuration file is usually where you rename routes, set base paths, or change scanning behaviour, and none of those keys appear in the README.

Getting a server running: the two commands

There are two entry points, and they serve different situations. For a new project, the README gives npx create-xmcp-app@latest. For an existing Next.js or Express project, it gives npx init-xmcp@latest. The split is deliberate. create-xmcp-app scaffolds a standalone server, while init-xmcp adds xmcp to an application that already has a routing or middleware story of its own. The Next.js and Express mention is the most concrete integration claim in the README, and it is worth reading narrowly: it says xmcp can be initialized on those projects, not that every feature behaves identically in both. Development runs with hot reloading, which the README lists as instant development feedback. That implies a dev server process watching the tools and prompts directories so that adding a file registers a new tool without a restart. The README does not name the dev command, so I cannot give you the exact invocation. Deployment is described as flexible across any platform, with a separate line for zero-configuration deployment with Vercel. Those two claims sit awkwardly together, since zero-configuration on one platform usually means that platform's build output is the one that has been exercised. Treat the Vercel path as the documented default and the any-platform path as something you will be validating yourself.

Where the documentation stops and the source starts

This is the main limitation, and it is a documentation limitation rather than an architectural one. The README is a landing page. It lists six features in a bulleted block and points to xmcp.dev and xmcp.dev/docs for everything else. The bullet text is one line per feature, with no example of a tool file, no middleware signature, no configuration schema, and no error behaviour. For a framework whose central promise is that a directory layout determines your server's public surface, the absence of a single example file is a real gap. You cannot tell from this material whether a tool is a default export, a named export, or an object with a handler field. You cannot tell what happens when two files would produce the same tool name, or whether a malformed file fails the build or is skipped at runtime. The security section is a reporting channel, an email address for vulnerabilities, which tells you the maintainers want reports but says nothing about the threat model of a generated server. None of this makes xmcp a bad choice. It means the docs site is load-bearing, and the README alone is not enough to evaluate the framework. If the docs site is equally thin, you are reading TypeScript source before you write your first tool.

What you give up compared to the official SDKs

The alternative is the official Model Context Protocol SDK for TypeScript, which is the lower-level option. With the SDK you construct a server object and register each tool by calling a method on it. The difference is not capability, it is where the structure lives. The SDK puts registration in your code, so the list of tools is explicit and greppable, and the handler signature is whatever the SDK defines rather than whatever a directory scanner infers. xmcp puts registration in the file system, so the list of tools is a directory listing and the handler signature is a convention the framework enforces. The SDK approach costs you boilerplate: every new tool is a registration call plus a handler, and authentication is something you wire into the transport yourself. The xmcp approach costs you explicitness: the server's surface is not visible in one file, and behaviour that depends on file naming is harder to trace than a function call. There is a third position, which is building directly on the protocol types with your own routing, and that is only worth it if you have opinions xmcp does not accommodate. The choice between xmcp and the SDK is really a choice about whether you want a framework opinion on layout. If you have already standardized tool registration across several services, xmcp's convention may conflict with it.

Versioning, licence, and what maintenance costs

xmcp is MIT licensed, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are preserved. That is the permissive end of the spectrum, and it means you can vendor the framework or ship it inside a closed product. It does not mean the project accepts liability, and the MIT text disclaims warranty. I am not a lawyer and this is not legal advice; if you are redistributing xmcp as part of a product, read the licence file in the repository rather than relying on the badge. On maintenance, the material shows three packages versioned in lockstep: xmcp, init-xmcp, and create-xmcp-app, all at 1.1.3 as of the most recent release. That lockstep is a good sign for upgrade predictability, since the scaffolder and the runtime move together. The cost side is that the scaffolder is the part you touch least. create-xmcp-app runs once, and init-xmcp runs once per project, so the version that matters day to day is xmcp itself. A major-version bump in xmcp is the event to watch, because file-system routing conventions are the kind of thing that changes in a major. The README gives no upgrade guide, no changelog link, and no compatibility matrix for the Next.js and Express integrations. Before adopting, check whether a 1.x to 2.x migration path is documented, because a convention change in a router is not a mechanical dependency bump.

Editorial conclusion

Adopt xmcp if you already write TypeScript and want MCP tool registration to follow the same convention-over-configuration pattern as your Next.js routes, and if you are willing to read the source when the docs stop short. Do not adopt it if you need a non-Node runtime, a language other than TypeScript, or a written specification of the middleware contract before you commit. Verify one thing first: whether the tools directory scanning and the middleware signature match your existing project layout, since the README shows only the bootstrap commands and not the file shape those commands expect.

Official sources

1. basementstudio/xmcp on GitHub
2. License: MIT
3. Project website
4. README
5. Releases