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

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.).

Quick Reference

File Structure

front/lib/api/actions/servers/{provider}/
├── metadata.ts           # Tool metadata and server info using createToolsRecord
├── tools/index.ts        # Tool handlers with exhaustive Record type
├── index.ts              # Server creation and tool registration
├── client.ts             # API client (optional)
└── helpers.ts            # Helper functions (optional)

Registration Files

front/lib/actions/mcp_internal_actions/constants.ts - Add server config with metadata: YOUR_SERVER
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)
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:

Check whether an OAuth provider exists in core/src/oauth/providers/ as {provider}.rs
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 { JSONSchema7 as JSONSchema } from "json-schema";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

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

export const YOUR_PROVIDER_TOOLS_METADATA = createToolsRecord({
  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",
    displayLabels: {
      running: "Listing Items",
      done: "List items",
    },
  },
  get_item: {
    description: "Get a single item by ID.",
    schema: {
      itemId: z.string().describe("The ID of the item to retrieve."),
    },
    stake: "never_ask",
    displayLabels: {
      running: "Retrieving item",
      done: "Retrieve item",
    },
  },
  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",
    displayLabels: {
      running: "Creating item",
      done: "Create item",
    },
  },
});

export const YOUR_PROVIDER_SERVER = {
  serverInfo: {
    name: "your_provider",
    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: Object.values(YOUR_PROVIDER_TOOLS_METADATA).map((t) => ({
    name: t.name,
    description: t.description,
    inputSchema: zodToJsonSchema(z.object(t.schema)) as JSONSchema,
    displayLabels: t.displayLabels,
  })),
  tools_stakes: Object.fromEntries(
    Object.values(YOUR_PROVIDER_TOOLS_METADATA).map((t) => [t.name, t.stake])
  ),
} as const satisfies ServerMetadata;

Key points:

createToolsRecord automatically adds the name property from the object key
tool keys become the source of truth
stake values map to review/approval expectations

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("No access token provided"));
    }

    try {
      const item = {};

      return new Ok([
        { type: "text" as const, text: `Retrieved item ${itemId}` },
        { type: "text" as const, text: JSON.stringify(item, null, 2) },
      ]);
    } catch (e) {
      return new Err(new MCPError("Failed to get item"));
    }
  },

  create_item: async ({ name, description }, { authInfo }) => {
    const token = authInfo?.token;
    if (!token) {
      return new Err(new MCPError("No access token provided"));
    }

    try {
      const item = {};

      return new Ok([
        { type: "text" as const, text: `Created item "${name}"` },
        { type: "text" as const, text: JSON.stringify(item, null, 2) },
      ]);
    } catch (e) {
      return new Err(new MCPError("Failed to create item"));
    }
  },
};

export const TOOLS = buildTools(YOUR_PROVIDER_TOOLS_METADATA, handlers);

Key points:

ToolHandlers<T> enforces exhaustive implementation
buildTools combines metadata and handlers into ToolDefinition[]
each handler receives typed params inferred from the schema
access the OAuth token via extra.authInfo?.token

3. Create `index.ts`

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

import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

import { makeInternalMCPServer } from "@app/lib/actions/mcp_internal_actions/utils";
import { registerTool } from "@app/lib/actions/mcp_internal_actions/wrappers";
import type { AgentLoopContextType } from "@app/lib/actions/types";
import { TOOLS } from "@app/lib/api/actions/servers/your_provider/tools";
import type { Authenticator } from "@app/lib/auth";

function createServer(
  auth: Authenticator,
  agentLoopContext?: AgentLoopContextType
): McpServer {
  const server = makeInternalMCPServer("your_provider");

  for (const tool of TOOLS) {
    registerTool(auth, agentLoopContext, server, tool, {
      monitoringName: "your_provider",
    });
  }

  return server;
}

export default createServer;

4. Register in `constants.ts`

Edit front/lib/actions/mcp_internal_actions/constants.ts:

import YOUR_PROVIDER_SERVER
add the server name to AVAILABLE_INTERNAL_MCP_SERVER_NAMES
add the config entry to INTERNAL_MCP_SERVERS

Example:

your_provider: {
  id: 99,
  availability: "manual",
  allowMultipleInstances: true,
  isRestricted: undefined,
  isPreview: false,
  tools_arguments_requiring_approval: undefined,
  tools_retry_policies: undefined,
  timeoutMs: undefined,
  metadata: YOUR_PROVIDER_SERVER,
},

Important properties:

id: unique stable ID, never change after deployment
availability: manual, auto, or auto_hidden_builder
allowMultipleInstances: true for OAuth-based integrations
isRestricted: feature-flag or plan gating function, if needed
isPreview: true for beta or preview integrations

5. Register in `servers/index.ts`

Edit front/lib/actions/mcp_internal_actions/servers/index.ts:

case "your_provider":
  return yourProviderServer(auth, agentLoopContext);

Optional: `client.ts` and `helpers.ts`

Use extra files when the integration grows beyond a few simple calls.

`client.ts`

Create a client when you need multiple API endpoints, response validation, auth header management, or retry logic.

`helpers.ts`

Create helpers for:

withAuth wrappers
response rendering
shared data transformations

Example withAuth pattern:

import { MCPError } from "@app/lib/actions/mcp_errors";
import type {
  ToolHandlerExtra,
  ToolHandlerResult,
} from "@app/lib/actions/mcp_internal_actions/tool_definition";
import { Err } from "@app/types/shared/result";

export async function withAuth<T>(
  { authInfo }: ToolHandlerExtra,
  action: (token: string) => Promise<ToolHandlerResult>
): Promise<ToolHandlerResult> {
  const token = authInfo?.token;
  if (!token) {
    return new Err(new MCPError("No access token provided"));
  }

  try {
    return await action(token);
  } catch (e) {
    return new Err(new MCPError("Operation failed"));
  }
}

Use client.ts / helpers.ts based on complexity:

no external API: keep everything in tools/index.ts
1-2 simple API calls: inline, maybe add helpers.ts
several API endpoints: create client.ts
complex response formatting: add dedicated rendering helpers

Alternative: function-based tools

If handlers need access to Authenticator directly, create tools through a function instead of a constant.

See front/lib/api/actions/servers/github/tools/index.ts for a full example.

Icon

Use an existing similar icon temporarily, then request the final icon from design/Sparkle and update the icon field once available.

Feature Flags and Restrictions

Gate preview or limited-access servers through isRestricted in the server config, using feature flags or plan checks as needed.

Best Practices

1. Render responses for token efficiency

Always convert API responses into focused, markdown-formatted output. Avoid returning raw JSON.stringify(apiResponse) with everything the upstream API sent.

Do:

keep only the fields the model needs
start with a short summary
format structured results consistently

Do not:

return full raw API responses
include pagination metadata or rate-limit details unless needed
duplicate the same data in multiple formats

2. Translate errors into actionable messages

Wrap failures in meaningful MCPErrors rather than exposing raw upstream errors.

3. Choose tool stakes carefully

never_ask: read-only operations
low: low-impact writes
medium: important writes
high: destructive or high-impact actions

4. Add `.describe()` to schema fields

Schema descriptions help the model supply the right parameters.

5. Validate external API responses with Zod

Validate every external response to catch API drift and unexpected payloads early.

Validation Checklist

Before marking implementation complete:

metadata.ts exists and uses createToolsRecord
tools/index.ts exists and uses ToolHandlers<typeof METADATA>
index.ts default-exports the server factory
the server is in AVAILABLE_INTERNAL_MCP_SERVER_NAMES
the server config is in INTERNAL_MCP_SERVERS
the server is registered in servers/index.ts
response rendering is implemented
a temporary icon is set
feature gating is configured if needed
npx tsgo --noEmit passes
npm run format:changed passes from the repo root
manual testing is complete

Troubleshooting

Server not appearing in the builder

check availability
check isRestricted
verify the server name is in AVAILABLE_INTERNAL_MCP_SERVER_NAMES

OAuth connection failing

verify the provider exists in core and front
check client ID / secret env vars
verify redirect URIs and scopes

Tools not working

verify the tool is registered
verify tools_stakes contains the tool names
test the API helper functions directly
confirm authInfo.token is propagated

Type errors

ensure the server name was added to AVAILABLE_INTERNAL_MCP_SERVER_NAMES
run npx tsgo --noEmit
if handler typing fails, re-check the metadata/handler mapping

Reference Implementations

front/lib/api/actions/servers/github/
front/lib/api/actions/servers/snowflake/
front/lib/api/actions/servers/google_calendar/
front/lib/api/actions/servers/agent_sidekick_context/
front/lib/api/actions/servers/agent_sidekick_agent_state/

Additional Resources

MCP SDK documentation: https://modelcontextprotocol.io/
existing server implementations in front/lib/api/actions/servers/
legacy implementations in front/lib/actions/mcp_internal_actions/servers/
OAuth providers in core/src/oauth/providers/

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

Install this agent skill to your local

Skill Files