MCP Server Slack — Block Kit messages, cursor pagination, and health probes via auth.test

SDK setup and authentication

Slack's official @slack/web-api package wraps the Slack Web API with TypeScript types and automatic rate limit retrying. Install it alongside Zod for MCP input validation.

import { WebClient, LogLevel } from '@slack/web-api';
import { z } from 'zod';

// Bot Token — starts with xoxb-
// Never use User Tokens (xoxp-) in server-side integrations
const slack = new WebClient(process.env.SLACK_BOT_TOKEN, {
  logLevel: LogLevel.ERROR,
  retryConfig: {
    retries: 3,
    factor: 1.5,
    minTimeout: 1000,
    maxTimeout: 30_000
  }
});

// The SDK handles Retry-After headers automatically when retryConfig is set.
// For manual axios usage, Slack rate limit responses are HTTP 429 with
// Retry-After header (seconds). Check the 'error' field for 'ratelimited'.

Slack tokens come in several types. Use the right one for each scenario:

Posting messages with Block Kit and confirm guards

The most critical Slack MCP tool is chat.postMessage. Messages sent to Slack cannot be recalled — once delivered, they reach every member of the channel. Always add a confirm guard to any send operation. Block Kit allows rich message composition with interactive elements, but for MCP tools focus on static Block Kit blocks: section, header, divider, and context.

server.tool('send_slack_message', {
  channel: z.string().describe('Channel ID (C...) or name (#general). Bot must be a member.'),
  text: z.string().describe('Plain text fallback for notifications and accessibility.'),
  blocks: z.array(z.object({
    type: z.enum(['section', 'header', 'divider', 'context']),
    text: z.object({
      type: z.enum(['mrkdwn', 'plain_text']),
      text: z.string()
    }).optional(),
    elements: z.array(z.any()).optional()
  })).optional().describe('Block Kit blocks for rich formatting. Falls back to text if omitted.'),
  thread_ts: z.string().optional().describe('Timestamp of parent message to reply in-thread.'),
  confirm: z.literal(true).describe('Messages cannot be unsent. Pass true to confirm.')
}, async ({ channel, text, blocks, thread_ts }) => {
  const res = await slack.chat.postMessage({
    channel,
    text,
    blocks,
    thread_ts,
    // unfurl_links: false reduces noise for URL-heavy messages
    unfurl_links: false
  });

  // Slack ALWAYS returns HTTP 200. Check res.ok, never HTTP status.
  if (!res.ok) {
    throw new Error(`Slack API error: ${res.error}`);
  }

  return {
    content: [{
      type: 'text',
      text: `Message sent. ts=${res.ts} channel=${res.channel}`
    }]
  };
});

Block Kit section block example for structured agent notifications:

const blocks = [
  {
    type: 'header',
    text: { type: 'plain_text', text: ':rotating_light: Deployment Alert' }
  },
  {
    type: 'section',
    text: {
      type: 'mrkdwn',
      text: `*Service:* \`${serviceName}\`\n*Status:* ${status}\n*Environment:* ${env}`
    }
  },
  {
    type: 'context',
    elements: [
      { type: 'mrkdwn', text: `Triggered at ` }
    ]
  }
];

Listing users with cursor pagination

Slack's users.list and other list methods use cursor-based pagination — not offset/limit. The SDK's paginator utility handles this automatically, but for MCP tools you typically want to expose pagination controls directly rather than fetching all pages server-side (which can take minutes for large workspaces).

server.tool('list_slack_users', {
  cursor: z.string().optional().describe('Pagination cursor from previous response next_cursor.'),
  limit: z.number().int().min(1).max(200).default(100).describe('Users per page. Max 200.')
}, async ({ cursor, limit }) => {
  const res = await slack.users.list({ cursor, limit });

  if (!res.ok) {
    throw new Error(`users.list failed: ${res.error}`);
  }

  const users = (res.members ?? [])
    .filter(u => !u.deleted && !u.is_bot)
    .map(u => ({
      id: u.id,
      name: u.name,
      real_name: u.real_name,
      email: u.profile?.email,
      is_admin: u.is_admin,
      tz: u.tz
    }));

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        users,
        next_cursor: res.response_metadata?.next_cursor ?? null
      }, null, 2)
    }]
  };
});

Listing conversations with type filters

Workspaces can contain public channels, private channels, DMs, and group DMs. Filter with the types parameter to avoid pulling irrelevant conversations. The bot only sees channels it has been invited to — for private channels, invitation must happen before conversations.list returns them.

server.tool('list_slack_channels', {
  types: z.array(z.enum(['public_channel', 'private_channel', 'mpim', 'im']))
    .default(['public_channel'])
    .describe('Channel types to include.'),
  exclude_archived: z.boolean().default(true),
  cursor: z.string().optional(),
  limit: z.number().int().min(1).max(1000).default(200)
}, async ({ types, exclude_archived, cursor, limit }) => {
  const res = await slack.conversations.list({
    types: types.join(','),
    exclude_archived,
    cursor,
    limit
  });

  if (!res.ok) throw new Error(`conversations.list failed: ${res.error}`);

  const channels = (res.channels ?? []).map(c => ({
    id: c.id,
    name: c.name,
    is_private: c.is_private,
    is_member: c.is_member,
    num_members: c.num_members,
    topic: c.topic?.value
  }));

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({ channels, next_cursor: res.response_metadata?.next_cursor ?? null }, null, 2)
    }]
  };
});

File uploads via the v2 method

Slack deprecated the original files.upload method in 2024. The v2 upload flow requires three steps: get an upload URL, upload the file bytes, and complete the upload with channel sharing. The @slack/web-api SDK's filesUploadV2 wraps all three steps.

server.tool('upload_slack_file', {
  channel: z.string().describe('Channel ID to share the file into.'),
  filename: z.string().describe('Filename with extension shown in Slack.'),
  content: z.string().describe('File content as UTF-8 text.'),
  title: z.string().optional(),
  initial_comment: z.string().optional().describe('Message posted alongside the file.')
}, async ({ channel, filename, content, title, initial_comment }) => {
  // SDK v7+ exposes filesUploadV2 which handles the 3-step flow
  const res = await slack.filesUploadV2({
    channel_id: channel,
    filename,
    content,
    title,
    initial_comment
  });

  if (!res.ok) throw new Error(`File upload failed: ${res.error}`);

  return {
    content: [{
      type: 'text',
      text: `File uploaded. id=${res.files?.[0]?.id}`
    }]
  };
});

Wiring /health/slack via auth.test

auth.test is the canonical Slack health probe. It requires no special permissions, validates token authenticity, returns the team and bot identifiers, and — critically — lists the token's granted OAuth scopes. A passing auth.test confirms your bot token is valid, not revoked, and associated with the workspace you expect.

// Express/Fastify health endpoint
app.get('/health/slack', async (req, res) => {
  try {
    const result = await slack.auth.test();

    if (!result.ok) {
      return res.status(503).json({
        status: 'unhealthy',
        error: result.error
      });
    }

    return res.json({
      status: 'healthy',
      bot_id: result.bot_id,
      team: result.team,
      team_id: result.team_id,
      user: result.user,       // The bot's display name
      scopes: result.response_metadata?.scopes
    });
  } catch (err: any) {
    return res.status(503).json({
      status: 'unhealthy',
      error: err.message,
      // Slack SDK wraps errors; check err.data?.error for the Slack error code
      slack_error: err.data?.error
    });
  }
});

Wire AliveMCP to poll /health/slack every 60 seconds. Token revocations are not gradual — a valid token becomes invalid instantly when an app is uninstalled or a token is rotated. AliveMCP's polling catches this before your first failed agent run.

Frequently asked questions

Further reading

• MCP Server Discord — Bot token auth, send messages with embeds, and guild member management
• MCP Server PagerDuty — create incidents, manage on-call schedules, and health probes via /users/me
• MCP Server Webhooks — sending structured payloads with retry logic
• MCP Server Health Check — wiring /health endpoints for uptime monitoring
• MCP Server Error Handling — structured errors and retry patterns