Installation

Starter Kit

If you want to create a dedicated MCP server with the minimum required setup, you can use the AdonisJS MCP Starter Kit. It provides a lightweight AdonisJS application pre-configured with MCP support — ideal when your application's sole purpose is to expose an MCP server.

npm init adonisjs@latest -- -K="batosai/adonisjs-mcp-starter-kit" my-mcp-server

TIP

If your goal is to add MCP capabilities to a larger application (with a database, authentication, views, etc.), skip the starter kit and follow the instructions below to install the package into an existing AdonisJS project.

Adding to an Existing Project

To get started, install Adonis MCP into your project using the ace command:

node ace add @jrmc/adonis-mcp

The installer will ask "Is Vinejs used for validation?" (Yes / No). If you choose Yes, the VineJS provider is registered and you can use request.validateUsing() in your MCP handlers. See Validation for details.

This will create a configuration file config/mcp.ts and set up the necessary directories for your MCP implementation.

Configuration

Server MCP configuration is located in the config/mcp.ts file. By default, the file looks like this:

import { defineConfig } from '@jrmc/adonis-mcp'

export default defineConfig({
  name: 'adonis-mcp-server',
  version: '1.0.0',
})

Configuration Options

• name: The name of your MCP server (used for identification)
• version: The version of your MCP server
• completions: Enable argument completions for prompts and resources (default: false)

Example with completions enabled:

import { defineConfig } from '@jrmc/adonis-mcp'

export default defineConfig({
  name: 'adonis-mcp-server',
  version: '1.0.0',
  completions: true, // Enable completions
})

Custom MCP Directory

By default, your MCP tools, resources, and prompts will be stored in app/mcp. If you want to use a different path, you can configure it in your adonisrc.ts file:

directories: {
  mcp: 'app/custom/mcp', // Optional: custom path for MCP files (defaults to 'app/mcp')
}

Registering the MCP Route

To expose your MCP server via HTTP, register the MCP route in your start/routes.ts file:

import { middleware } from '#start/kernel'
import router from '@adonisjs/core/services/router'

// Register MCP route (defaults to /mcp)
router.mcp()

You can also specify a custom path and apply middleware:

// With authentication middleware
router.mcp('/custom-mcp-path').use(middleware.auth())

CSRF Protection

Important

If you have CSRF protection enabled in your application, you must exclude the MCP route from CSRF validation. MCP clients typically don't include CSRF tokens in their requests.

In your config/shield.ts file, add the MCP route to the CSRF exceptions:

export const shieldConfig = defineConfig({
  csrf: {
    enabled: true,
    exceptRoutes: [
      '/mcp', // Or your custom MCP path
    ],
  },
})