Create custom tools via a local MCP server

This tutorial walks you through the process of adding custom tools to the Xata Agent. We do this by creating an MCP server, which the Agent then runs via the local stdio protocol.

Step 1: Create the MCP server in TypeScript

We will be creating the MCP server using the MCP Typescript SDK. As a convenience, you can create MCP servers in the apps/dbagent/mcp-source folder of the Agent repo. This is already set up with the correct dependencies and typescript configuration. However, this is only a convenience, you can create the MCP server any way you like, the Agent requires only the resulting .js file.

As an example MCP server, let's use the following, which you can save under apps/dbagent/mcp-source/quick-start.js:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

// Create an MCP server
const server = new McpServer({
  name: 'XataAgentToolDemo',
  version: '1.0.0'
});

// Add a couple of tools

server.tool('findLatestDBVersion', { dbName: z.string() }, async ({ dbName }) => {
  if (dbName === 'PostgreSQL') {
    return { content: [{ type: 'text', text: '17' }] };
  } else {
    return { content: [{ type: 'text', text: 'Not supported' }] };
  }
});

server.tool('addNumbers', { a: z.number(), b: z.number() }, async ({ a, b }) => ({
  content: [{ type: 'text', text: String(a + b) }]
}));

// Start receiving messages on stdin and sending messages on stdout
const transport = new StdioServerTransport();
await server.connect(transport);

Step 2: Compile TypeScript to the JS file

If you are using the Agent repo as recommended above, you can compile all files from mcp-source by running:

pnpm build:mcp-servers

This should create a file quick-start.js under apps/dbagent/mcp-srouce/dist.

Step 3: Add the MCP server to your production mcp-servers folder

Once you have the MCP server as a JS file, you can make it available to the Agent by simply copying it in the top-level mcp-servers folder. The Agent automatically looks into that folder when executed via the Docker compose file.

Step 4: Enable the MCP server in the UI

Go to the MCP page in the Agent UI and enable your server:

And test the new tool in the chat: