Building an MCP Server with Nx

Since the Model Context Protocol (MCP) was released by Anthropic in late 2024, it has quickly become an important part of the AI ecosystem. The MCP provides an open standard for connecting AI agents to the rest of the world - the web, software systems and developer tools, just to name a few examples.

We've been busy building the Nx MCP server, which gives LLMs deep access to your monorepo's structure. It helps AI tools to better understand your workspace architecture, browse the Nx docs and even trigger actions in your IDE like executing generators or visualizing the graph.

There are many examples of MCP servers for popular tools popping up all over the place. Check out the official MCP repo to see a long list of reference servers as well as official and community integrations.

Whatever you're building, it's becoming more and more important to ensure that AI systems can interact with your software. So let's learn how to build your very own MCP server to make your technology be usable for AI - all from an Nx monorepo!

In this series of blog posts, we'll be using a fictional startup as an example: Astra Arcana - a bewitched SaaS company that lets you cast spells from anywhere with a few simple clicks.

Screenshot of the Astra Arcana app visualizing a spell

You can go and try casting some spells right away at https://astra-arcana.pages.dev/

Of course, like any modern software company, they need to be ready for the coming shift towards AI - let's help them by building an MCP server that lets you browse ingredients and cast spells directly from your AI chat!

Setting up the Server

Code Along

If you want to code along and build your own mcp server, clone the https://github.com/MaxKless/astra-arcana repo on GitHub to get started.

Astra Arcana is built in an Nx monorepo, where the web app and api live. There's also a shared types library as well as the Typescript SDK, which lets users programmatically cast spells.

apps
 ├── web
 └── api
libs
 ├── spellcasting-types
 └── spellcasting-sdk

We will create a new Node application that contains our MCP server and use the Typescript SDK to power it.

Creating the MCP Server

MCP are JSON-RPC servers that communicate with clients via stdio or http. Thankfully, the official Typescript SDK abstracts away large pieces of the implementation, making it easier to get started - let's get started by installing it.

❯

npm install @modelcontextprotocol/sdk

We'll continue by installing the @nx/node plugin and using it to generate a new Node application:

❯

npx nx add @nx/node

❯

npx nx generate @nx/node:application --directory=apps/mcp-server --framework=none --no-interactive

This generates a basic node application:

UPDATE package.json
CREATE apps/mcp-server/src/assets/.gitkeep
CREATE apps/mcp-server/src/main.ts
CREATE apps/mcp-server/tsconfig.app.json
CREATE apps/mcp-server/tsconfig.json
UPDATE nx.json
CREATE apps/mcp-server/package.json
UPDATE tsconfig.json

In package.json, you'll see that Nx has configured a build and serve target for our app that uses webpack. Now that our setup is ready, let's implement the actual server.

First, let's import some things and set up an instance of McpServer. This is part of the MCP SDK and will take care of actually implementing the Protocol Layer of the MCP specification, for example how to communicate with the client.

apps/mcp-server/src/main.ts
import { SpellcastingSDK } from '@astra-arcana/spellcasting-sdk';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new McpServer({
  name: 'Astra Arcana',
  version: '1.0.0',
});

Next, we'll register a set of MCP tools. A tool is essentially a function that the AI model can call, passing some input parameters if necessary. Instead of constructing API calls manually, our tools will expose three main parts of casting a spell with the Spellcasting SDK: Ingredients, Incantations and Recipes. This is really the core piece of the MCP server, as it defines what it can do. There are other features you can implement, but currently, tools are by far the most widely supported and important part.

apps/mcp-server/src/main.ts
const sdk = new SpellcastingSDK();

server.tool('get-ingredients', async () => {
  const ingredients = await sdk.getIngredients();
  return {
    content: [{ type: 'text', text: JSON.stringify(ingredients) }],
  };
});

server.tool('get-incantations', async () => {
  const incantations = await sdk.getIncantations();
  return {
    content: [{ type: 'text', text: JSON.stringify(incantations) }],
  };
});

server.tool('get-recipes', async () => {
  const recipes = await sdk.getRecipes();
  return {
    content: [{ type: 'text', text: JSON.stringify(recipes) }],
  };
});

Finally, let's implement the Transport Layer, letting the MCP server listen to and send messages via process inputs and outputs (stdio). It's only a few lines of code:

apps/mcp-server/src/main.ts
const transport = new StdioServerTransport();
(async () => {
  await server.connect(transport);
})();

And just like that, we've built our very own MCP server! Let's make sure it works.

Testing with the MCP Inspector

Anthropic has not just come up with the protocol, they've also created a great ecosystem around it: Various SDKs, reference servers and a visual testing tool: The MCP Inspector.

Let's modify our serve target to use the Inspector, letting us explore our newly created server. First, delete the existing serve target in apps/mcp-server/package.json , as it doesn't really apply to our use case. Replace it with this

apps/mcp-server/package.json
"serve": {
  "command": "npx -y @modelcontextprotocol/inspector node ./apps/mcp-server/dist/main.js",
  "dependsOn": ["build"],
  "continuous": true
}

Let's break it down:

the command runs the Inspector, pointing to the build output location of our MCP server
"dependsOn": ["build"] tells nx to always run the build before this target, making sure that the bundled javascript is available
"continuous": true marks the serve as a continuous task so that will work properly in more complex task pipelines

You can see the result by running npx nx serve mcp-server and looking at the website it spins up (usually on http://localhost:6274 ).

The sidebar contains all the information required to start the server - here the STDIO transport is correctly preselected as well as the command needed to start the server.

Screenshot of the MCP Inspector sidebar

After clicking on the Connect button, the server is started in the background and you'll be able to see the available tools and call them under the Tools tab.

Screenshot of the MCP Inspector showing the available tools

Agents that can take actions

The get-* tools that we've built are already super useful and budding spellcasters will be glad to have help in perfecting their concoctions and learning ancient incantations. However, where the power of AI agents really starts to shine is when they go beyond just reading data and start taking actions. Let's give AI the ability to cast spells. 🪄

We'll register another tool in apps/mcp-server/src/main.ts

apps/mcp-server/src/main.ts
import { z } from 'zod';

// ... previous tools

server.tool(
  'cast-spell',
  'Lets the user cast a spell via the Astra Arcana API.',
  { ingredients: z.array(z.string()), incantations: z.array(z.string()) },
  async ({ ingredients, incantations }) => {
    const result = await sdk.castSpell(ingredients, incantations);
    return {
      content: [{ type: 'text', text: JSON.stringify(result) }],
    };
  }
);

There are two key differences in this tool definition:

We've passed a description string as the second argument. You can do this for every tool in order to describe what to use it for and what will happen when the agent calls it. cast-spell is sort of self-explanatory but it's still good practice to add a description and increase the model's chances of picking the right tool for the job. You can even add more annotations to mark a tool as read-only, destructive or more.
We've passed an object that defines the shape of the input using zod. This lets the agent know how to structure the inputs that are passed to the tool. ingredients and incantations as arrays of strings aren't very complicated, but you could also add descriptions to each individual option to explain what it does. The full feature set of zod is available to define exactly what's possible with each tool.

Now, let's try it out in an actual agent. I'll use VSCode & GitHub Copilot for this but any agent implementation with MCP support will do. I really like Windsurf or Cursor, for example.

.vscode/mcp.json
{
  "servers": {
    "astra-arcana": {
      "command": "node",
      "args": ["/path/astra-arcana/apps/mcp-server/dist/main.js"]
    }
  }
}

Once you open a Copilot chat in Agent mode, the MCP server will start automatically and you should see all four tools available

Screenshot of the VSCode quickinput listing available MCP tools

Let's try to cast a spell! For obvious reasons, I want to make sure that I'm writing high-quality blog posts and could use a magic boost. You can see that the AI agent uses all the tools to figure out what's available and then tries to cast the spell. Some models might ask for permission first or ask follow up questions to make sure they're getting it right.

Screenshot of a conversation with Copilot that uses the built MCP tools

After casting, you can head over to https://astra-arcana.pages.dev/ and check the logs to see your spell! 🎉

Screenshot of the Astra Arcana app showing the cast spell in the browser

Publishing to npm

Of course, now that we've built our magical MCP server, we want to make sure people can use it easily. Let's go through the process of publishing an executable file to the npm registry. In the future, anyone will be able to run npx @astra-arcana/mcp-server and spin it up immediately!

Learn More About nx release

This section goes over the release process of this specific example. If you want to learn how to use nx release in detail, I recommend checking out Juri's great course on the topic: https://www.epicweb.dev/tutorials/versioning-and-releasing-npm-packages-with-nx

Publishing Pre-Requisites

In order to have our bundled code be executable via npx, we need to add a shebang (#!/usr/bin/env node) to the first line of the file. We'll make sure this is added in a new script in the apps/mcp-server directory called setup-publish.js.

apps/mcp-server/setup-publish.js
import path from 'path';
import fs from 'fs';

const distDir = path.resolve(import.meta.dirname, './dist');
const distMainJsPath = path.resolve(distDir, 'main.js');
const mainJsContent = fs.readFileSync(distMainJsPath, 'utf8');
const shebang = '#!/usr/bin/env node\n';

if (!mainJsContent.startsWith(shebang)) {
  fs.writeFileSync(distMainJsPath, shebang + mainJsContent);
  console.log('Shebang added');
}

console.log('Setup completed successfully!');

We'll also set up a target that calls this script after making sure the main bundle is built.

apps/mcp-server/package.json
"setup-publish": {
  "command": "node apps/mcp-server/setup-publish.js",
  "dependsOn": ["build"]
}

While we're in package.json , let's also make sure that our package is publishable and let npx and similar tools know where to find the executable javascript file.

apps/mcp-server/package.json
{
  "name": "@astra-arcana/mcp-server",
  "version": "0.0.1",
- "private": true,
+ "private": false,
+ "bin": "./main.js",
  // ...

Local Publishing with Verdaccio

Publishing

Keep in mind that the @astra-arcana/mcp-server package already exists on the official npm registry, so we will only publish to a local registry.

At Nx, we use an awesome open-source tool called Verdaccio. It's a lightweight implementation of a local npm registry - let's use it to test out our publishing flow.

You can add verdaccio to the repo by running the setup-verdaccio generator:

❯

npx nx g @nx/js:setup-verdaccio

This will create a verdaccio config and an nx target to spin it up at the root of our workspace. Start the local registry by running.

❯

npx nx run @astra-arcana/source:local-registry

On http://localhost:4873/ , you'll see an instance of verdaccio running with no packages published yet. Let's change that!

Configuring Nx Release

Now that everything is set up, let's configure nx release to actually version our package, generate changelogs and publish to npm.

There are a couple of things we want to configure. Check out the comprehensive release documentation to learn more about the different configuration options.

Since we're in a monorepo with different kinds of packages, we have to let nx release know which ones to configure releases for - in this case, only the mcp-server app
When releasing, we need to make sure that not only is the version in the repo's package.json is incremented, but also the version in the dist folder that we'll actually release from. We can do this by setting manifestRootsToUpdate.
We have to make sure the dist folder exists, so we'll run our new setup-publish action first by specifying the command in preVersionCommand .
Since our mcp server will be released independently, we configure the changelogs to be generated per-project instead of for the entire workspace.

nx.json
"release": {
  "projects": ["mcp-server"],
  "version": {
    "manifestRootsToUpdate": [
      "{projectRoot}",
      "{projectRoot}/dist"
    ],
    "preVersionCommand": "npx nx run mcp-server:setup-publish"
  },
  "changelog": {
    "projectChangelogs": true,
    "workspaceChangelog": false
  }
}

This is enough to configure nx release for our exact use case. With this, we can run npx nx release --dry-run . Nx will run the setup-publish target, prompt you for the kind of version change that's happening and give you a preview of what the result would be.

Screenshot of the version prompt asked by nx release

If you're happy with the results, rerun the command without --dry-run and watch as nx release does its magic. The versions will be updated across both package.json files, and a changelog file, a git commit and tag will be created.

In order to release to npm, we have to add some final configuration to nx.json .

nx.json
"targetDefaults": {
  // ... other config
  "nx-release-publish": {
    "options": {
      "packageRoot": "{projectRoot}/dist"
    }
  }
}

This will tell the automatically generated nx-release-publish target where to find the built files so that it can publish them to npm (or verdaccio, in our case). After running npx nx release publish , refresh Verdaccio to see the successfully published package! 🎉 You can spin up the MCP server using the published version by running npx @astra-arcana/mcp-server and try it out.

That's it! You can view the @astra-arcana/mcp-server package on npm here: https://www.npmjs.com/package/@astra-arcana/mcp-server