Extending MCP

Add new MCP tools and modify existing servers for custom functionality

Model Context Protocol (MCP) servers expose external services as tools that the AI agent can call. Genie Helper uses three MCP servers: Directus (data layer), Ollama (LLM inference), and Stagehand (browser automation).

MCP Server Architecture

AnythingLLM Agent
  ↓
storage/plugins/anythingllm_mcp_servers.json  (config)
  ↓
scripts/
  ├── directus-mcp-server.mjs   (17 tools)
  ├── ollama-mcp-server.mjs     (3 tools)
  └── stagehand-mcp-server.mjs  (9 tools)

Servers are auto-booted on AnythingLLM startup via patched server/utils/boot/index.js.

MCP Server Configuration

Servers are defined in storage/plugins/anythingllm_mcp_servers.json:

{
  "mcpServers": {
    "directus": {
      "command": "node",
      "args": ["/var/www/vhosts/geniehelper.com/agentx/scripts/directus-mcp-server.mjs"],
      "env": {
        "DIRECTUS_URL": "http://127.0.0.1:8055",
        "DIRECTUS_EMAIL": "[e-mail]",
        "DIRECTUS_PASSWORD": "password"
      }
    },
    "ollama": {
      "command": "node",
      "args": ["/var/www/vhosts/geniehelper.com/agentx/scripts/ollama-mcp-server.mjs"],
      "env": {
        "OLLAMA_URL": "http://127.0.0.1:11434",
        "OLLAMA_MODEL": "dolphin3:8b-llama3.1-q4_K_M"
      }
    },
    "stagehand": {
      "command": "node",
      "args": ["/var/www/vhosts/geniehelper.com/agentx/scripts/stagehand-mcp-server.mjs"],
      "env": {
        "STAGEHAND_URL": "http://127.0.0.1:3002",
        "STAGEHAND_MODEL": "ollama/qwen-2.5"
      }
    }
  }
}

After modifying this file, restart AnythingLLM: pm2 restart anything-llm

Adding a Tool to Existing Server

Let’s add a new tool to the Directus MCP server.

Example: Add bulk-delete-items Tool

File: scripts/directus-mcp-server.mjs

server.tool(
  "bulk-delete-items",
  "Delete multiple items from a Directus collection by ID array",
  {
    collection: z.string().describe("Collection name"),
    ids: z.array(z.string()).describe("Array of item IDs to delete"),
  },
  async ({ collection, ids }) => {
    const promises = ids.map(id => 
      directusFetch(`/items/${collection}/${id}`, { method: "DELETE" })
    );
    const results = await Promise.allSettled(promises);
    const deleted = results.filter(r => r.status === "fulfilled").length;
    const failed = results.length - deleted;
    return { 
      content: [{ 
        type: "text", 
        text: `Deleted ${deleted} items. Failed: ${failed}` 
      }] 
    };
  }
);

Tool Definition Anatomy

server.tool(
  "tool-name",           // Unique identifier (kebab-case)
  "Human description",   // Shown to AI agent
  {
    // Zod schema for parameters
    param1: z.string().describe("What this param does"),
    param2: z.number().optional().describe("Optional param"),
  },
  async (params) => {
    // Implementation
    return {
      content: [{ 
        type: "text", 
        text: "Result data as string or JSON" 
      }]
    };
  }
);

Key points:

• Tool names use kebab-case
• Descriptions help the AI understand when to use the tool
• Zod schemas validate and document parameters
• Always include .describe() for parameters
• Return format: { content: [{ type: "text", text: "..." }] }

Creating a New MCP Server

Let’s create a new MCP server for Stripe payment integration.

1. Create Server Script

File: scripts/stripe-mcp-server.mjs

#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import Stripe from "stripe";

const STRIPE_SECRET_KEY = process.env.STRIPE_SECRET_KEY;
const stripe = new Stripe(STRIPE_SECRET_KEY);

const server = new McpServer({ name: "stripe", version: "1.0.0" });

server.tool(
  "list-customers",
  "List Stripe customers with optional email filter",
  {
    email: z.string().optional().describe("Filter by customer email"),
    limit: z.number().optional().describe("Max customers to return (default 10)"),
  },
  async ({ email, limit }) => {
    const params = { limit: limit || 10 };
    if (email) params.email = email;
    
    const customers = await stripe.customers.list(params);
    return { 
      content: [{ 
        type: "text", 
        text: JSON.stringify(customers.data, null, 2) 
      }] 
    };
  }
);

server.tool(
  "create-payment-link",
  "Create a Stripe payment link for a subscription or one-time purchase",
  {
    price_id: z.string().describe("Stripe Price ID"),
    quantity: z.number().optional().describe("Quantity (default 1)"),
  },
  async ({ price_id, quantity }) => {
    const paymentLink = await stripe.paymentLinks.create({
      line_items: [{ price: price_id, quantity: quantity || 1 }],
    });
    return { 
      content: [{ 
        type: "text", 
        text: `Payment link created: ${paymentLink.url}` 
      }] 
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

2. Make Script Executable

chmod +x scripts/stripe-mcp-server.mjs

3. Add to MCP Config

File: storage/plugins/anythingllm_mcp_servers.json

{
  "mcpServers": {
    "directus": { ... },
    "ollama": { ... },
    "stagehand": { ... },
    "stripe": {
      "command": "node",
      "args": ["/var/www/vhosts/geniehelper.com/agentx/scripts/stripe-mcp-server.mjs"],
      "env": {
        "STRIPE_SECRET_KEY": "sk_live_..."
      }
    }
  }
}

4. Install Dependencies

npm install stripe

5. Restart AnythingLLM

pm2 restart anything-llm

6. Verify Tools Loaded

Check AnythingLLM logs:

pm2 logs anything-llm --lines 50 | grep "MCP server"

You should see:

MCP server 'stripe' loaded with 2 tools

MCP Server Templates

Basic HTTP API Server

#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const API_URL = process.env.API_URL || "https://api.example.com";
const API_KEY = process.env.API_KEY;

async function apiFetch(path, opts = {}) {
  const res = await fetch(`${API_URL}${path}`, {
    ...opts,
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      ...opts.headers,
    },
  });
  const text = await res.text();
  if (!res.ok) throw new Error(`API ${path} failed (${res.status}): ${text}`);
  try {
    return JSON.parse(text);
  } catch {
    return text;
  }
}

const server = new McpServer({ name: "my-api", version: "1.0.0" });

server.tool(
  "get-data",
  "Fetch data from the API",
  {
    id: z.string().describe("Record ID"),
  },
  async ({ id }) => {
    const data = await apiFetch(`/records/${id}`);
    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Database Connection Server

#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import mysql from "mysql2/promise";

const pool = mysql.createPool({
  host: process.env.DB_HOST || "localhost",
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
});

const server = new McpServer({ name: "mysql", version: "1.0.0" });

server.tool(
  "query",
  "Execute a SQL query and return results",
  {
    sql: z.string().describe("SQL query to execute"),
    params: z.array(z.any()).optional().describe("Query parameters"),
  },
  async ({ sql, params }) => {
    const [rows] = await pool.execute(sql, params || []);
    return { content: [{ type: "text", text: JSON.stringify(rows, null, 2) }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Existing MCP Server Tools

Directus MCP (17 tools)

Collections:

• list-collections — List all custom collections
• get-collection-schema — Get field schema for a collection

Items CRUD:

• read-items — Read items with filtering, sorting, pagination
• read-item — Read single item by ID
• create-item — Create new item
• update-item — Update existing item
• delete-item — Delete item
• search-items — Full-text search

Flows:

• trigger-flow — Trigger Directus Flow by UUID
• list-flows — List all flows

Users:

• get-me — Get current user info
• list-users — List all users
• get-user — Get user by ID
• create-user — Create new user
• update-user — Update user

Files:

• list-files — List uploaded files
• get-file — Get file metadata

See: scripts/directus-mcp-server.mjs

Ollama MCP (3 tools)

• list-models — List locally available models
• generate — Single-turn completion
• chat — Multi-turn chat with history

See: scripts/ollama-mcp-server.mjs

Stagehand MCP (9 tools)

• start-session — Create browser session
• navigate — Navigate to URL
• act — Perform action (click, type, etc.)
• extract — Extract data using AI
• observe — Observe page elements
• close-session — End browser session
• set-cookies — Inject cookies
• get-cookies — Retrieve cookies
• screenshot — Capture screenshot

See: scripts/stagehand-mcp-server.mjs

Best Practices

Tool Naming

• Use kebab-case: get-user, create-payment-link
• Be descriptive: bulk-delete-items not delete-many
• Group by resource: user-create, user-update, user-delete

Parameter Descriptions

Always use .describe() for Zod schemas:

// Good
user_id: z.string().describe("Directus user ID (UUID format)")

// Bad
user_id: z.string()

Descriptions are shown to the AI agent and improve tool selection accuracy.

Error Handling

server.tool(
  "risky-operation",
  "Operation that might fail",
  { id: z.string() },
  async ({ id }) => {
    try {
      const result = await dangerousOperation(id);
      return { content: [{ type: "text", text: JSON.stringify(result) }] };
    } catch (err) {
      return { 
        content: [{ 
          type: "text", 
          text: `Error: ${err.message}` 
        }] 
      };
    }
  }
);

Caching

For expensive operations, use caching:

const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

server.tool(
  "get-expensive-data",
  "Fetch data with caching",
  { id: z.string() },
  async ({ id }) => {
    const cached = cache.get(id);
    if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
      return { content: [{ type: "text", text: cached.data }] };
    }
    
    const data = await expensiveOperation(id);
    cache.set(id, { data: JSON.stringify(data), timestamp: Date.now() });
    return { content: [{ type: "text", text: JSON.stringify(data) }] };
  }
);

See: server/utils/cache/extractCache.js for cache implementation pattern.

Debugging MCP Servers

View Server Logs

pm2 logs anything-llm --lines 200 | grep MCP

Test Tool Directly

MCP servers use stdio transport. Test with:

echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list-models"},"id":1}' | \
  node scripts/ollama-mcp-server.mjs

Common Issues

Tool not appearing in agent:

• Check MCP config syntax in anythingllm_mcp_servers.json
• Verify script path is absolute
• Restart AnythingLLM: pm2 restart anything-llm

Environment variables not loaded:

• Set in env block of MCP config, not in shell
• Use absolute paths for any file references

Server crashes on startup:

• Check pm2 logs anything-llm for stack trace
• Verify all dependencies installed: npm install
• Test script directly: node scripts/my-mcp-server.mjs

Auto-boot Implementation

MCP servers are automatically started by patched AnythingLLM boot sequence.

File: server/utils/boot/index.js

const { bootMCPServers } = require('./mcpBoot');

async function boot() {
  // ... existing boot logic
  
  // Boot MCP servers
  await bootMCPServers();
  
  // ... rest of boot
}

This ensures MCP servers are available when the agent starts.

Next Steps

Custom Actions

Use MCP tools in Action Runner flows

Project Structure

Understand where MCP servers fit