Slack Code MCP

Model Context Protocol (MCP) is a standardized way for LLMs to use external systems through tools. This repository provides a focused remote MCP server for Slack Web API so agents can discover operations and execute validated API calls with a fixed low-context tool surface.

Design references:

• Cloudflare Code Mode MCP

• Anthropic: Building Effective Agents (advanced tool use)

The server supports streamable-http transport via /mcp.

Server in this Repository

Tools Exposed

Why Better Than Official MCP Patterns

Compared to official/provider MCP servers that expose many endpoint-level tools, this implementation is better for agent behavior:

• Fixed 3-tool interface keeps context and tool-selection ambiguity low.

• Two-step control loop (search then execute) aligns with how agents plan and call tools.

• Write safety is explicit: server policy gate plus per-call confirmation token.

• Performance controls (catalog cache, read cache, response truncation) reduce latency and context bloat.

Access from Any MCP Client

If your MCP client supports remote MCP directly:

{
  "mcpServers": {
    "slack-code-mcp": {
      "transport": "streamable_http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "x-user-id": "default"
      }
    }
  }
}

If your client needs a command bridge:

{
  "mcpServers": {
    "slack-code-mcp": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:3000/mcp"],
      "env": {
        "MCP_REMOTE_HEADERS": "{\"x-user-id\":\"default\"}"
      }
    }
  }
}

Quick Start

cd slack
npm install
npm run build
npm test

Seed access token from environment:

SLACK_BOT_TOKEN='<xoxb-token>' npm run seed:token

Start server:

TOKEN_STORE_PATH=./data/tokens.integration.json \
TOKEN_ENCRYPTION_KEY_BASE64='<seed-output-key>' \
PORT=3000 HOST=127.0.0.1 npm run dev

Smoke test:

curl -sS http://127.0.0.1:3000/healthz
MCP_URL=http://127.0.0.1:3000/mcp USER_ID=default npm run smoke:mcp

Tool Calling Flow

1. Call auth_status.

2. Call search with intent (for example, list channels).

3. Pick an operation_id.

4. Call execute with required params in body.

5. For writes: call dry_run=true, then replay with confirm_write_token and ALLOW_WRITES=true.

Example search input:

{
  "query": "post a message to a channel",
  "limit": 5
}

Example read execute input:

{
  "operation_id": "POST /conversations.list"
}

Example write execute dry run:

{
  "operation_id": "POST /chat.postMessage",
  "body": {
    "channel": "C12345678",
    "text": "Hello from Slack Code MCP"
  },
  "dry_run": true
}

Configuration

Key environment variables:

• ALLOW_WRITES (default false)

• REQUEST_TIMEOUT_MS

• MAX_RETRIES

• CATALOG_CACHE_PATH

• READ_CACHE_TTL_MS

• EXECUTE_MAX_BODY_BYTES

• EXECUTE_BODY_PREVIEW_CHARS

See .env.example for the full set.

Safety Model

• Mutating operations are blocked unless ALLOW_WRITES=true.

• Mutating calls require confirm_write_token from matching dry-run request.

• Sensitive headers and body fields are redacted.

Performance Model

• Fixed 3-tool MCP surface to keep context small.

• Persisted catalog cache enables fast startup and asynchronous refresh.

• Conditional docs refresh (ETag/Last-Modified) where available.

• Short TTL cache for repeated read operations.

• Execute body truncation controls context overhead.

Troubleshooting

• MCP Inspector connect failure: confirm URL is http://127.0.0.1:3000/mcp and server is running.

• AUTH_REQUIRED: seed token or complete OAuth bootstrap.

• Write blocked: set ALLOW_WRITES=true and use returned confirm_write_token.

• Slack API error with HTTP 200: Slack methods often return { ok: false, error: "..." }; this is surfaced as tool error.

Development

• Source: src

• Tests: tests

• References: REFERENCES.md