Slack Code

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

Server	Description	URL
slack-code-mcp	Search + execute over Slack Web API operations with OAuth and write guardrails	http://127.0.0.1:3000/mcp

Tools Exposed

Tool	Purpose	Typical use
search	Finds ranked operations from Slack method catalog + docs context	"list channels", "post message", "get conversation history"
execute	Validates and executes operation by operation_id	Read and write API calls with typed validation
auth_status	Returns auth status for current caller	Preflight before execute

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