MCP Client Setup

MCP Client Setup

Slackquery uses remote MCP Streamable HTTP. A generic endpoint is:

https://slackquery.example.com/mcp

Replace the hostname with your deployment. Do not configure a stdio command, the Dagster URL, a health endpoint, or a legacy SSE endpoint.

Portable client model

Client schemas vary, but preserve these concepts:

• server name: slackquery;
• transport: streamable-http, http, or the client's equivalent;
• URL: the complete /mcp endpoint;
• optional bearer authorization header.

Conceptual unauthenticated configuration:

{
  "mcpServers": {
    "slackquery": {
      "transport": "streamable-http",
      "url": "https://slackquery.example.com/mcp"
    }
  }
}

Conceptual authenticated configuration:

{
  "mcpServers": {
    "slackquery": {
      "transport": "streamable-http",
      "url": "https://slackquery.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SLACKQUERY_BEARER_TOKEN}"
      }
    }
  }
}

Environment interpolation is client-specific. Use the client's protected secret store where available. Never commit or paste a literal bearer token.

Preflight

From the same network context as the client:

curl -fsS https://slackquery.example.com/healthz
curl -fsS https://slackquery.example.com/readyz

Liveness confirms the HTTP process. Readiness confirms that a published artifact can be opened read-only. Neither endpoint validates relevance quality, and readiness does not continuously probe query embedding.

Expected tools and resource

The client should discover:

• search_slack;
• get_slack_message;
• get_slack_thread;
• list_slack_scopes;
• resource slackquery://guide.

If these are absent, reload client configuration and verify current Streamable HTTP MCP support.

Smoke test

1. Call list_slack_scopes with a small limit.
2. Search a known exact term with search_slack in lexical mode.
3. Search a paraphrased question in semantic mode.
4. Repeat in hybrid mode and inspect component ranks and fused score.
5. Expand one promising result with get_slack_message or get_slack_thread.

Do not put real workspace, channel, user, message, or artifact identifiers in public configuration examples or issue reports.

Recommended client policy

Use search_slack in hybrid mode by default. Discover stable filters with
list_slack_scopes. Narrow workspace, channel, author, and time constraints before
raising limits. Use lexical mode for exact errors, references, URLs, filenames,
quotes, code, and acronyms; use semantic mode for paraphrased questions. Expand
only promising messages or threads. Preserve source metadata when citing results.
Scores are ranking signals, not probabilities. No result does not prove absence.

Tool behavior

search_slack

Accepts query, mode, optional scope filters, inclusive microsecond timestamp bounds, a result limit, and an opaque cursor. Hybrid is the default. The response identifies the immutable serving snapshot for traceability. A cursor is bound to that snapshot and the complete request; discard it after publication or request changes.

list_slack_scopes

Returns stable scope references, display labels, coverage summaries, and first and last timestamps. Use stable references for filtering instead of mutable names.

get_slack_message

Returns the exact document and optional bounded same-channel context. Channel adjacency does not imply thread membership.

get_slack_thread

Returns a selected thread chronologically. Use it before drawing conclusions about discussion context or sequence.

Security and citation

Archived messages may contain sensitive operational or personal content.

• Preserve equivalent access control in the MCP client and downstream system.
• Do not paste secrets or unrelated private messages into public issues or logs.
• Distinguish direct quotation from interpretation.
• Share permalinks only with recipients who have appropriate access.
• Never log authorization headers.

Common setup failures

Symptom	Resolution
Connection refused	Check routing, firewall, proxy, and service bind address.
404	Use the complete /mcp URL.
Protocol mismatch	Select Streamable HTTP, not stdio or legacy SSE.
401	Configure the bearer token through a protected secret field.
Semantic/hybrid error	Ask the operator to verify query-embedding health; lexical may still work.
Cursor rejected	Restart pagination after publication or request changes.

See Retrieval and RRF and Troubleshooting.