dust-mcp-server

MCP Server Runbook: Adding Internal MCP Server Integrations for Remote Platforms

This runbook provides step-by-step instructions for creating new internal MCP server integrations in Dust that connect to remote platforms (e.g., Jira, HubSpot, Salesforce, etc.).

MVP Fast Path

For a minimal new server (no OAuth, no external API yet — just the skeleton to register and test):

1. Create front/lib/api/actions/servers/{provider}/metadata.ts with a literal metadata array
2. Create front/lib/api/actions/servers/{provider}/tools/index.ts with stub handlers
3. Create front/lib/api/actions/servers/{provider}/index.ts with createServer
4. Register in constants.ts and servers/index.ts
5. Add the server to SERVER_SOURCES in bm25_tool_search_utils.test.ts
6. Add at least one BM25 query case to bm25_tool_search.test.ts

See the BM25 Tests section below for the test setup. This gives you a runnable skeleton with type-checked tool descriptions before writing any real API calls.

Quick Reference

File Structure

front/lib/api/actions/servers/{provider}/
├── metadata.ts           # Tool metadata array and server info
├── tools/index.ts        # Schema-inferred handlers and built tools
├── index.ts              # Provider-local server creation and registration
├── client.ts             # API client (optional)
└── helpers.ts            # Helper functions (optional)

Registration Files

1. front/lib/actions/mcp_internal_actions/constants.ts - Add server config with metadata: YOUR_SERVER
2. front/lib/actions/mcp_internal_actions/servers/index.ts - Import and register in switch statement

OAuth Requirements (if the platform requires OAuth)

• OAuth provider must already exist in front/lib/api/oauth/providers/{provider}.ts
• OAuth core implementation must exist in core/src/oauth/providers/{provider}.rs
• OAuth scopes must be configured for the required API access
• Server's authorization field must reference the OAuth provider

Common Gotchas

• Do not forget to add the server to AVAILABLE_INTERNAL_MCP_SERVER_NAMES array
• Server IDs must be stable and unique; never change them once deployed
• Tool stakes must be configured appropriately (never_ask, low, medium, high)
• Every internal tool must define displayLabels, toolCostCategory, and freeUsage
• Tool descriptions should start with a bare infinitive/base verb like List, Get, Search, Create, or Update
• Always implement proper error handling with Result types
• Handle OAuth token refresh automatically through the withAuth pattern

Prerequisites

OAuth Configuration (if required)

If the remote platform requires OAuth authentication:

1. Check whether an OAuth provider exists in core/src/oauth/providers/ as {provider}.rs
2. Check whether a front OAuth provider exists in front/lib/api/oauth/providers/{provider}.ts

If the OAuth provider does not exist, implement it first in core and front:

• create core/src/oauth/providers/{provider}.rs
• implement the OAuth flow: authorization URL, token exchange, refresh
• register the provider in core/src/oauth/providers/mod.rs
• create front/lib/api/oauth/providers/{provider}.ts for the front-end OAuth setup

See existing providers like hubspot.rs or jira.rs for reference implementations.

Research Phase

Before starting implementation, research the platform API:

1. API Documentation

• find the official API documentation
• identify REST endpoints vs GraphQL vs SDK usage
• note rate limits and pagination requirements

2. Authentication Method

• OAuth 2.0, preferred for user-facing integrations
• API key / bearer token, simpler but less secure
• required OAuth scopes

3. Available Operations

Document the operations you want to expose:

• read operations: list, get, search
• write operations: create, update, delete
• special operations: transitions, associations, etc.

Step-by-Step Implementation

1. Create metadata.ts

Create front/lib/api/actions/servers/{provider}/metadata.ts:

import type { ServerMetadata } from "@app/lib/actions/mcp_internal_actions/tool_definition";
import { z } from "zod";

export const YOUR_PROVIDER_SERVER_NAME = "your_provider" as const;

export const YOUR_PROVIDER_TOOLS_METADATA = [
  {
    name: "list_items",
    description: "List all items accessible to the user.",
    schema: {
      pageToken: z.string().optional().describe("Page token for pagination."),
      maxResults: z.number().optional().describe("Maximum results to return."),
    },
    stake: "never_ask",
    toolCostCategory: "advanced",
    freeUsage: false,
    displayLabels: {
      running: "Listing Items",
      done: "List items",
    },
  },
  {
    name: "get_item",
    description: "Get a single item by ID.",
    schema: {
      itemId: z.string().describe("The ID of the item to retrieve."),
    },
    stake: "never_ask",
    toolCostCategory: "advanced",
    freeUsage: false,
    displayLabels: {
      running: "Retrieving item",
      done: "Retrieve item",
    },
  },
  {
    name: "create_item",
    description: "Create a new item.",
    schema: {
      name: z.string().describe("Name of the item."),
      description: z.string().optional().describe("Description of the item."),
    },
    stake: "low",
    toolCostCategory: "advanced",
    freeUsage: false,
    displayLabels: {
      running: "Creating item",
      done: "Create item",
    },
  },
] as const;

export const YOUR_PROVIDER_SERVER = {
  serverInfo: {
    name: YOUR_PROVIDER_SERVER_NAME,
    version: "1.0.0",
    description: "Short description of what this integration does.",
    authorization: {
      provider: "your_provider",
      supported_use_cases: ["personal_actions", "platform_actions"],
    },
    icon: "YourProviderLogo",
    documentationUrl: "https://docs.dust.tt/docs/your-provider",
    instructions: null,
  },
  tools: YOUR_PROVIDER_TOOLS_METADATA,
} as const satisfies ServerMetadata;

Key points:

• Use snake_case for the tool names
• Internal tools must include displayLabels; unlike remote MCP tools, these labels are required
• Set toolCostCategory and freeUsage deliberately, following a comparable existing server
• tool descriptions start with a bare infinitive/base verb such as List, Get, Search, Create, Update, or Retrieve; avoid noun phrases, articles, gerunds, and third-person verbs because descriptions are part of the BM25 tool-search corpus (see BM25-Friendly Descriptions below)
• stake values map to review/approval expectations

BM25-Friendly Descriptions (MCP3 rule)

Tool names and descriptions both drive BM25 retrieval. Names are the strongest signal — they must be consistent and follow the verb_noun convention (e.g., list_warehouses, get_workbook). Descriptions are the secondary signal: write each one as if answering "what user intent does this tool serve?"

Rules:

1. Start with a bare infinitive verb: List, Get, Search, Create, Update, Send, Delete
2. Include platform-specific nouns that users mention in queries: warehouse, workbook, ticket, channel
3. Include common synonyms inline when the platform uses an unusual term: worksheets (sheets/tabs)
4. Include the platform name when it adds specificity (e.g., Databricks workspace, Excel workbook), but don't lead with the full brand name or repeat it redundantly across every tool
5. For platform-specific servers, avoid adding location qualifiers (e.g., in OneDrive, in SharePoint) to every tool — BM25 treats these as content tokens, so they widen the match surface and cause your tools to surface on location-based queries (e.g., a Drive search) even when the user intended a different tool

Examples:

// BAD — noun phrase, redundant "Microsoft Excel", location noise
description: "Microsoft Excel file listing from OneDrive and SharePoint."

// BAD — gerund
description: "Listing all SQL warehouses in Databricks."

// BAD — third-person verb
description: "Lists all SQL warehouses available in Databricks."

// GOOD — bare infinitive, platform noun, no location noise
description: "List all SQL warehouses available in the Databricks workspace."

// GOOD — synonym in parentheses helps BM25 match "sheets" and "tabs"
description: "Get a list of all worksheets (sheets/tabs) in an Excel workbook."

// GOOD — verb + context + common synonyms
description: "Search Slack channels, messages, and threads by keyword or topic."

Test your descriptions: add a BM25 query case (see next section) before merging. If your expected tool doesn't score > 0 in its own server-scoped index, the description is too generic or missing the key tokens the user will type.

2. Create tools/index.ts

Create front/lib/api/actions/servers/{provider}/tools/index.ts:

import { MCPError } from "@app/lib/actions/mcp_errors";
import type { ToolHandlers } from "@app/lib/actions/mcp_internal_actions/tool_definition";
import { buildTools } from "@app/lib/actions/mcp_internal_actions/tool_definition";
import { YOUR_PROVIDER_TOOLS_METADATA } from "@app/lib/api/actions/servers/your_provider/metadata";
import { Err, Ok } from "@app/types/shared/result";

const handlers: ToolHandlers<typeof YOUR_PROVIDER_TOOLS_METADATA> = {
  list_items: async ({ pageToken, maxResults }, { authInfo }) => {
    const token = authInfo?.token;
    if (!token) {
      return new Err(new MCPError("No access token provided"));
    }

    try {
      const items = [];

      return new Ok([
        { type: "text" as const, text: `Found ${items.length} items` },
        { type: "text" as const, text: JSON.stringify({ items }, null, 2) },
      ]);
    } catch (e) {
      return new Err(new MCPError("Failed to list items"));
    }
  },

  get_item: async ({ itemId }, { authInfo }) => {
    const token = authInfo?.token;
    if (!token) {
      return new Err(new MCPError

---

*Content truncated.*